流年流月 API

POST/api/v1/chinese/bazi/flow

该接口用于预测分析，计算年度（大运）和月度流年流月柱，并返回每个时间段与本命盘的作用关系和激活神煞。

完整 URL

https://api.freeastroapi.com/api/v1/chinese/bazi/flow

调用范围限制

为保证性能，年份范围限制为每次请求 1 年。多年度预测请连续发起请求。

响应模式

summary：最快响应。不包含解读文本，仅返回最少元数据。

standard：返回包含解读和说明的完整细节。

debug：包含计算审计日志，用于排查问题。

字段选择

include 省略时默认返回 interactions 和 stars。

传入 ["interactions"] 或 ["stars"] 时，它会作为白名单使用。

推荐格式是字符串数组。为了向后兼容，也仍然接受 "interactions,stars" 这类逗号分隔字符串。

字典响应模式

dictionary_response: true 会把作用关系和神煞返回为整数 ID，并在根字段 x_dict 中提供映射。

最佳实践：在应用加载时请求一次 /dictionary 接口并缓存它，然后在后续 flow 请求中使用 dictionary_response: false（默认值），并在客户端解析 ID。

请求参数

参数	类型	必填	说明
year	integer	Yes	出生年份。
month	integer	Yes	出生月份，范围 1-12。
day	integer	Yes	出生日期，范围 1-31。
hour	integer	Yes	出生小时，范围 0-23。
minute	integer	Yes	出生分钟，范围 0-59。
city	string	Yes	城市名称，用于 /geo/search 坐标解析。
lat	float	No	纬度。提供 lat/lng 时可直接使用坐标。
lng	float	No	经度。提供 lat/lng 时可直接使用坐标。
sex	string	Yes	'M' 或 'F'。
target_year	integer	Yes	预测开始年份。
target_year_end	integer	No	结束年份，最多 1 年范围。默认 target_year + 1。
mode	string	No	'summary'、'standard' 或 'debug'。
include	array[string]	No	可选白名单：['interactions', 'stars']。省略时默认返回两者，也兼容逗号分隔字符串。
dictionary_response	boolean	No	返回紧凑整数 ID 和 x_dict。默认 false。

调用示例

curl -X POST "https://api.freeastroapi.com/api/v1/chinese/bazi/flow" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "lat": 28.6139,
    "lng": 77.2090,
    "sex": "M",
    "target_year": 2024,
    "mode": "summary"
}'

响应数据

{
  "target_year": 2024,
  "target_year_end": 2025,
  "years": [
    {
      "year": 2024,
      "gan_zhi": "甲辰",
      "gan": "甲",
      "zhi": "辰",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "ten_god": "Direct Wealth",
      "interactions": [1005, 2021],
      "stars": [4005],
      "months": [
        {
          "index": 1,
          "name": "February 2024",
          "gan_zhi": "丙寅",
          "gan": "丙",
          "zhi": "寅",
          "ten_god": "Friend",
          "interactions": [1012],
          "stars": [4001, 4005]
        }
      ]
    }
  ],
  "x_dict": {
    "1005": {
      "type": "Stem Combination",
      "name": "甲-己 Combination",
      "stems": ["甲", "己"],
      "transform_to": "Earth"
    },
    "2021": {
      "type": "Branch Clash",
      "name": "寅-申 Clash",
      "branches": ["寅", "申"]
    }
  }
}