玄境 · 斗數 · 介面

紫微斗數 API

排盤、格局、運限皆為決定性計算，不經模型；同一個生辰永遠得到同一張盤。可直接以 JSON 取用，無需登入。

快速開始

curl -X POST https://fate.novice.tw/api/ziwei.php \
  -H 'Content-Type: application/json' \
  -d '{"y":1971,"m":2,"d":10,"h":21,"gender":"男","view_year":2023}'

也接受 GET 與 application/x-www-form-urlencoded，參數同名。回應為 UTF-8 JSON，不壓縮、不快取（Cache-Control: no-store）。

請求參數

必要

參數	型別	說明
`y` `m` `d`	整數	生年、月、日。國曆或農曆由 `cal` 決定

選用

參數	預設	說明
`cal`	`greg`	`greg` 國曆、`lunar` 農曆
`leap`	`0`	農曆閏月，僅 `cal=lunar` 時有意義
`h`	`11`	出生小時 0–23。`23` 為晚子時，會換日
`gender`	`男`	`男`／`女`，決定大限順逆
`view_year`	—	指定流年（農曆年），附大限、流年、小限與運限格局
`read`	`0`	`1` 附一段解盤。無快取時較慢（約 10–25 秒）
`format`	`full`	`lite` 省略形容星、不判局說明與 `read`，回應約小一半

別名：cal_type、year、month、day、 hour、flow_year 亦可使用。

回應結構

{
  "ok": true,
  "chart": {
    "solar": { "year": 1971, "month": 2, "day": 10, "hour": 21 },
    "minguo": "民國60年",
    "lunar": { "year": 1971, "month": 1, "day": 15, "leap": false, "label": "農曆 辛亥年 正月十五" },
    "gender": "男",
    "year_ganzhi": "辛亥",
    "hour_name": "亥時",
    "five": "木三局",
    "soul_star": "文曲",
    "body_star": "天機",
    "yin_yang": "陰",
    "yin_yang_label": "陰男",
    "forward": false,
    "soul_palace": { "stem": "辛", "branch": "卯" }
  },
  "palaces": [
    {
      "name": "命宮", "stem": "辛", "branch": "卯",
      "major": [ { "name": "太陽", "brightness": "廟", "mutagen": "權" } ],
      "minor": ["文曲"], "adjective": ["龍池", "旬空"],
      "is_soul": true, "is_body": false,
      "void": false,
      "decadal": [3, 12]
    }
  ],
  "patterns": {
    "matched": [
      { "code": "gui_02", "name": "日出扶桑", "category": "honor",
        "verdict": "auspicious", "clause": "日在卯守命是也，守官祿宮亦然。",
        "plain": "太陽坐卯守命，如日出東方，主早年得志、聲名早著。",
        "evidence": ["居卯宮", "太陽同宮（卯宮）"], "source_id": 55 }
    ],
    "undecidable": [ { "name": "祿馬佩印", "clause": "…", "note": "條件不足，暫不判定。" } ],
    "deferred": ["風雲際會", "祿衰馬困", "衣錦還鄉", "枯木逢春"]
  },
  "grade": {
    "grade": "上次",
    "why": "命宮主星廟旺、吉曜聚會，並見化權、科；雖入2局，但同見1個凶局，故不列上上",
    "detail": { "temple": true, "fallen": false, "lucky": ["文曲"], "killer": [],
                "mutagens": ["權","科"], "matched": 2 }
  },
  "transit": {
    "ganzhi": "癸卯", "nominal_age": 53,
    "soul_palace": { "stem": "辛", "branch": "卯" },
    "soul_majors": ["太陽", "天梁"],
    "small_limit": { "index": 9, "branch": "酉", "palace": "遷移" },
    "mutagens": [ { "star": "破軍", "mutagen": "祿", "palace": "僕役", "branch": "申" } ],
    "flow_stars": [ { "name": "流祿", "index": 0, "branch": "子", "palace": "子女", "type": "convention" } ],
    "flow_source": "convention",
    "decadal": { "range": [53, 62], "ganzhi": "戊戌", "majors": ["廉貞", "天府"], "mutagens": [] },
    "patterns": [
      { "code": "za_04", "name": "衣錦還鄉", "level": "decadal",
        "level_name": "大限", "evidence": ["53 歲行戌宮（四墓）"] }
    ]
  },
  "read": { "source": "template", "text": "", "sections": [] }
}

transit 僅在帶 view_year 時出現，否則為 null。未帶 read=1 且 format=lite 時不附 read。

即時範例

以下為本頁載入時實際呼叫 API 的結果（format=lite、1971-02-10 21:00 男）。

{
    "chart": {
        "lunar": "農曆 辛亥年 正月十五",
        "year_ganzhi": "辛亥",
        "five": "木三局",
        "yin_yang_label": "陰男",
        "forward": false
    },
    "soul_palace": {
        "name": "命宮",
        "stem": "辛",
        "branch": "卯",
        "major": [
            "太陽（廟）",
            "天梁（廟）"
        ]
    },
    "patterns": [
        "日出扶桑・吉",
        "馬落空亡・凶"
    ],
    "grade": "上次",
    "transit": {
        "ganzhi": "癸卯",
        "nominal_age": 53,
        "decadal": "戊戌",
        "patterns": [
            "衣錦還鄉"
        ]
    }
}

錯誤回應

HTTP	`code`	情境
400	`bad_calendar`	`cal` 不是 greg／lunar
400	`missing_date`	缺年、月、日
400	`bad_hour`	小時不在 0–23
422	`invalid_date`	該日期不存在（含農曆閏月誤填）
422	`out_of_range`	超出 1900–2100 年

{ "ok": false, "error": "這個國曆日期不存在", "code": "invalid_date" }

資料來源與可信度

回應中每一個判斷都有來源。接 API 時請依欄位分別看待，不要一律當成同等可信。

欄位	來源	說明
`chart`・`palaces`	排盤規則	定宮、安星、四化皆為決定性計算，已與 iztro 交叉驗證 5,520 項
`patterns.matched`	《紫微斗數全書》	條文照錄，`source_id` 可直接對應古籍原文
`patterns.undecidable`	原文條件不足	見於書中但無法定出判準，僅存其名。不是沒有命中，是不判定
`patterns.deferred`	須行運方能論	雜局中已可判定的四局，需帶 `view_year` 才會在 `transit.patterns` 出現
`transit.soul_palace`	原書明文	流年命宮＝太歲地支之宮，卷三逐支明列
`transit.flow_stars`	`convention`	通行安星法，原書未載。固定標為 `convention`，請勿與古籍同等看待
`read`	選用	規則敘事不依賴模型；`read=1` 才可能呼叫模型，且輸出必經驗證閘門，未通過即退回 `template`

使用限制

目前不提供金鑰。排盤本身不計費，但有流量護欄：同一來源每分鐘 60 次、每小時 600 次；同一 IP 子網每小時 2,000 次。超額回 429，並附 Retry-After 與 retry（秒）欄位，請據此退避重試，不要原速重打。
read=1 每來源每小時最多 8 次真正呼叫模型。超過時仍回完整盤面，但 read.source 會是 template，並附 X-Ziwei-Read: throttled 標頭。
同一張盤的解盤有快取，重複呼叫不會再次產生費用，也不計入上述次數。
批次用途（例如一次算上百張盤）請先來信，不要用並行腳本硬打；護欄會先擋下，對你我都沒有好處。
年干支以農曆正月初一為界（斗數傳統），與八字以立春分年不同。
閏月採「十五日前算上月、十六日起算下月」；晚子時（23:00 後）換日。

← 回紫微斗數排盤 · 古籍原文 · 排盤