开发文档
API Shop 玄学算法接口使用指南
快速开始
注册账号后，在控制台创建 API 密钥，即可通过 HTTP 请求调用算法接口。所有接口均返回 JSON 格式数据。
# 获取八字命盘（GET 请求）
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
-H "X-API-Key: your_key_here"
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
-H "X-API-Key: your_key_here"
认证方式
所有 API 请求需在 HTTP Header 中携带 API 密钥：
X-API-Key: <your_api_key>
也可通过 query 参数传递：?api_key=your_key
可在 控制台 → 密钥
公共请求参数
以下参数在 /api/bazi 和 /api/bazi/fortune
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| date_type | int | 否 | 1 | 日期类型：1=公历，2=农历 |
| year | int | 否 | 当前年 | 出生年份（1~9999） |
| month | int | 否 | 当前月 | 出生月份（1~12） |
| day | int | 否 | 当前日 | 出生日（1~31） |
| hour | int | 否 | 当前时 | 出生时辰（0~23，24小时制） |
| sex | int | 否 | 1 | 性别：1=男，0=女 |
| name | string | 否 | 空 | 姓名（仅用于展示） |
| lang | string | 否 | zh-CN | 返回语言：zh-CN=简体，zh-TW=繁体，en=英文 |
参数值非法时自动回退到当前时间的对应值，但日期本身的合法性（如2月30日）会被校验并返回 400 错误。
通用响应格式
{
"code": 200,
"message": "success",
"data": { ... }
}
"code": 200,
"message": "success",
"data": { ... }
}
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，200 表示成功 |
| message | string | 状态描述信息 |
| data | object/null | 业务数据，失败时可能为 null |
接口详情
GET
/api/bazi
根据出生时间获取完整的八字命盘信息，包括四柱八字、五行、十神、神煞、大运、命格、喜用神、批八字分析、当前运势等。
该接口会自动定位到“当前”的大运/流年/流月/流日，无需额外传运势参数。
请求参数
参见 公共请求参数，无额外参数。
响应字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| lang | string | 返回语言 |
| solar | string | 公历出生时间（YYYY-MM-DD HH:00） |
| lunar | string | 农历出生时间 |
| name | string | 姓名 |
| gender | int | 性别：1=男，0=女 |
| age | int | 周岁年龄 |
| zodiac | string | 生肖 |
| constellation | string | 星座 |
| solarTerm | string | 节气 |
| yinYang | string | 年干阴阳（阳/阴） |
| riZhu | string | 日柱天干 |
| fiveElements | object | 五行统计 + 旺衰 |
| fourPillars | object | 四柱信息（干支、天干、地支、纳音、十神、星运、自坐、空亡、藏干、合刑冲害） |
| usefulGods | object | 喜用神（用神/喜神/忌神/仇神/闲神） |
| spiritStars | object | 神煞（四柱各自） |
| decadeFortune | array | 大运列表（全部步骤） |
| yearFortune | array | 小运列表 |
| destiny | object | 命盘信息（命宫、身宫、胎元、胎息、起运、命格、旺衰、强弱） |
| currentFortune | object | 当前运势（自动定位到当前大运/流年/流月/流日） |
| analysis | object | 批八字文字结论（性格、事业、财运、姻缘、健康等） |
| decadeFortuneAnalysis | object | 大运运势 + 流年运势（含未交运前 + 9步大运各10年流年） |
| chuanGongPalace | array | 串宫压运（盲派） |
| ganZhiAnalysis | array | 干支刑冲合害分析（原局 + 当前大运/流年引动） |
请求示例
# 公历 1990年6月15日 10时 男
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
-H "X-API-Key: your_key_here"
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
-H "X-API-Key: your_key_here"
响应示例（精简）
{
"code": 200,
"message": "success",
"data": {
"lang": "zh-CN",
"solar": "1990-06-15 10:00",
"lunar": "庚午年五月廿三日 巳时",
"name": "张三",
"gender": 1,
"age": 35,
"zodiac": "马",
"constellation": "双子座",
"solarTerm": "芒种",
"riZhu": "辛",
"fiveElements": { ... },
"fourPillars": { ... },
"usefulGods": { ... },
"spiritStars": { ... },
"decadeFortune": [ ... ],
"destiny": { ... },
"currentFortune": { ... },
"analysis": { ... },
"decadeFortuneAnalysis": { ... },
"chuanGongPalace": [ ... ],
"ganZhiAnalysis": [ ... ]
}
}
"code": 200,
"message": "success",
"data": {
"lang": "zh-CN",
"solar": "1990-06-15 10:00",
"lunar": "庚午年五月廿三日 巳时",
"name": "张三",
"gender": 1,
"age": 35,
"zodiac": "马",
"constellation": "双子座",
"solarTerm": "芒种",
"riZhu": "辛",
"fiveElements": { ... },
"fourPillars": { ... },
"usefulGods": { ... },
"spiritStars": { ... },
"decadeFortune": [ ... ],
"destiny": { ... },
"currentFortune": { ... },
"analysis": { ... },
"decadeFortuneAnalysis": { ... },
"chuanGongPalace": [ ... ],
"ganZhiAnalysis": [ ... ]
}
}
currentFortune 定位规则
该接口会在每次请求时自动定位到“今天”的运势：
- 1. 以当前时间决定“当前”的公历年/月/日
- 2. 遍历大运列表找到包含当前年份的大运
- 3. 取该大运下全部 10 年流年填充 yearFortune
- 4. 流月以当前流年对应的公历年计算 12 个月
- 5. 流日按当前公历年月计算当月每日
- 6. ganZhiAnalysis 会用原局 + 当前大运 + 当前流年重新计算引动关系
GET
/api/bazi/fortune
按层级钻取大运/流年/流月/流日/流时，支持从大运到流时四个层级的逐级下钻查询。
请求参数
参见 公共请求参数
| 参数 | 类型 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|
| decade | int | 0~9 | 0 | 大运序号；0=返回所有大运列表 |
| year_idx | int | 0~10 | 0 | 流年序号；0=该大运全部 10 年列表 |
| month_idx | int | 0~12 | 0 | 流月序号；0=该流年全年 12 个月 |
| day_idx | int | 0~31 | 0 | 流日序号；0=该流月当月每日 |
层级约束规则
参数之间存在层级依赖关系，必须逐级指定：
- • 指定 year_idx 时，decade 不能为 0
- • 指定 month_idx 时，year_idx 不能为 0
- • 指定 day_idx 时，month_idx 不能为 0
违反约束将返回 400 错误。
查询层级与返回数据
| 层级 | 参数组合 | 返回字段 |
|---|---|---|
| L0 | 无参数 / decade=0 | decadeFortune[] — 全部大运列表 |
| L1 | decade=N | decade + yearFortune[] + monthlyPillars[] + dailyPillars[] + hourlyPillars[] + ganZhiAnalysis |
| L2 | decade=N + year_idx=M | L1 + year |
| L3 | + month_idx=K | L2 + monthlyPillar |
| L4 | + day_idx=D | L3 + dailyPillar |
数据模型
PillarInfo（单柱统一信息）
四柱、大运、流年、流月、流日均使用此结构：
stemBranch, heavenStem, earthBranch, tenGod, growthStage,
hiddenStems[], ziZuo, xingYun, void, nayin, shenSha[]
hiddenStems[], ziZuo, xingYun, void, nayin, shenSha[]
运势项类型
FortuneDecadeItem（大运项）= PillarInfo + index + startYear + endYear + age
FortuneYearItem（流年项）= PillarInfo + index + age + year + xiaoYun
FortuneMonthPillar（流月柱）= PillarInfo + month
FortuneDayPillar（流日柱）= PillarInfo + date（"YYYY-MM-DD"）
FortuneHourPillar（流时柱）= PillarInfo + hour
ganZhiAnalysis（岁运引动）
二元数组 [天干留意[], 地支作用[]]，带 [大运]/[流年]/[流月] 前缀的条目代表岁运引动到原局四柱的对应关系。流日干支当前不进入此分析。
请求示例
# 示例1：获取全部大运列表（Level 0）
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1" \
-H "X-API-Key: your_key_here"
# 示例2：查询第3步大运的全部流年（Level 1）
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1&decade=3" \
-H "X-API-Key: your_key_here"
# 示例3：查询指定流月（Level 3）
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1&decade=3&year_idx=5&month_idx=6" \
-H "X-API-Key: your_key_here"
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1" \
-H "X-API-Key: your_key_here"
# 示例2：查询第3步大运的全部流年（Level 1）
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1&decade=3" \
-H "X-API-Key: your_key_here"
# 示例3：查询指定流月（Level 3）
curl "https://www.zfate.com/api/bazi/fortune?year=1990&month=6&day=15&hour=10&sex=1&decade=3&year_idx=5&month_idx=6" \
-H "X-API-Key: your_key_here"
响应示例（Level 1，精简）
{
"code": 200,
"message": "success",
"data": {
"decade": { /* FortuneDecadeItem */ },
"yearFortune": [ /* FortuneYearItem × 10 */ ],
"monthlyPillars": [ /* FortuneMonthPillar × 12 */ ],
"dailyPillars": [ /* FortuneDayPillar × N */ ],
"hourlyPillars": [ /* FortuneHourPillar × 12 */ ],
"ganZhiAnalysis": [
["戊癸合化火", "[大运]丙辛合化水", ...],
["子丑六合", "[大运]寅午半合", ...]
]
}
}
"code": 200,
"message": "success",
"data": {
"decade": { /* FortuneDecadeItem */ },
"yearFortune": [ /* FortuneYearItem × 10 */ ],
"monthlyPillars": [ /* FortuneMonthPillar × 12 */ ],
"dailyPillars": [ /* FortuneDayPillar × N */ ],
"hourlyPillars": [ /* FortuneHourPillar × 12 */ ],
"ganZhiAnalysis": [
["戊癸合化火", "[大运]丙辛合化水", ...],
["子丑六合", "[大运]寅午半合", ...]
]
}
}
错误码说明
| HTTP 状态码 | code | 说明 |
|---|---|---|
| 200 | 200 | 请求成功 |
| 400 | 400 | 请求参数错误（日期越界、层级约束违反等） |
| 401 | 401 | 未携带 API 密钥 |
| 403 | 403 | API 密钥无效或已停用 |
| 429 | 429 | 超过每日调用限额 |
如遇问题，请联系技术支持或查看 用量