API Shop - 八字算命API接口服務 — 專業八字排盤與流年運勢SDK

快速開始

註冊帳號後，在控制台建立 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"

認證方式

所有 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	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"

回應範例（精簡）

{
  "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=回傳所有大運列表
year_idx	int	0~10	流年序號；0=該大運全部 10 年列表
month_idx	int	0~12	流月序號；0=該流年全年 12 個月
day_idx	int	0~31	流日序號；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[]

運勢項類型

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"

回應範例（Level 1，精簡）

{
  "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	超過每日呼叫限額

開發文件

快速開始

認證方式

公用請求參數

通用回應格式

介面詳情

請求參數

回應欄位說明

請求範例

回應範例（精簡）

currentFortune 定位規則

請求參數

層級約束規則

查詢層級與回傳資料

資料模型

請求範例

回應範例（Level 1，精簡）

錯誤碼說明