API 指南

想知道這套 API 在實際服務中如何運作嗎？ 您可以在以同一套引擎運作的 AI 八字應用程式 INTA – Life is Timing 中，親自體驗八字分析與 AI 對話。 INTA 就是這套 API 的實際運作範例。 INTA 的 AI 語音回應（TTS）也由同一套技術堆疊驅動 — 語音 API 將於日後公開。

快速入門

HRUM 提供會記憶的 AI、八字分析與 LLM 轉售。請依照以下 3 個步驟開始：

基本網址為 https://api.hrum.ai（API）與 https://console.hrum.ai（主控台）。舊網址 api.float.do、console.float.do、api.inta.do 仍可正常使用，若已完成串接則無須更改。

1. 取得 API 金鑰 - 在主控台註冊後，於 API 金鑰畫面中建立金鑰（金鑰僅在建立後顯示一次）。從註冊到錯誤處理的完整流程，請參閱開發者入門指南。
2. 發送請求 - 依照下方範例發送 POST 請求。
3. 處理回應 - 從 JSON 回應中取出八字資料。

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

注意 User-Agent： Python 標準函式庫 urllib 的預設 User-Agent（Python-urllib/3.x）會觸發安全規則，回傳 403（error 1010）。requests、OpenAI SDK、Node、curl 皆可正常運作。若使用 urllib 或自行開發的 HTTP 用戶端，請自行設定 User-Agent: <app-name>/<version> 標頭。 （實測：python-requests 通過、OpenAI/Python 通過、node 通過、Python-urllib 403）

節省費用 — 請儲存結果並重複使用。 每一筆成功的請求都會個別計費。萬年曆、紫微斗數、合盤、占星、終身八字的結果，只要出生年月日時與選項相同，再次呼叫也會得到相同結果，因此請將第一次的回應存入資料庫（例如以請求本文的雜湊值為鍵），之後直接使用已儲存的值。今日運勢、運勢走勢這類會隨日期變動的結果，請把日期也放進鍵中。詳情請參閱冪等性。

API 參考文件

HRUM 提供會記憶的 AI、八字分析與 LLM 轉售。

• 變更（2026-10-14）： 韓文回應的語氣統一為一致的敬語體（內容與欄位皆無變更）
• 新增（2026-10-14）： 無法辨識時區名稱時，成功回應會附上 warnings（UNKNOWN_TIMEZONE）。計算仍和以往一樣使用預設時區，沒有警告時回應與以往相同 — 回應警告
• 新增（2026-10-17）： AI 八字解讀、解讀記憶、報告的 birth 現在可接受與萬年曆 API 相同的出生地、時區、閏月欄位（isLeapMonth、timezone、座標、country、zaSiRule、birthTimePrecision）。未傳送時計算與以往相同 — AI 八字解讀 API

RIDM Memory API

為每位終端使用者託管對話記憶，並為 ridm/* 模型加上記憶層。記憶僅限 ridm/*，OpenAI/Google 模型則原樣轉售 — 同一個模型，不同的產品。也支援自動插入 YouTube 字幕。

沒有工作階段 — 一個永不結束的工作階段。 以相同的 user 呼叫，對話就會一直延續下去。每次呼叫時，伺服器會自動附上最近 historyCount 則對話輪次與 recallCount 則長期記憶（摘要、個人資料、記住的事實、持續中的煩惱），因此您只需傳送一則新訊息。要往回參照多遠，由這兩個數值調整；每位終端使用者可儲存的訊息數上限則由 memoryCap 設定。若想自行管理歷史紀錄，請省略 historyCount，並依 OpenAI 的方式把先前的對話放進 messages 一起傳送。

對話再長，費用也不會線性增加。 較舊的助理輪次會自動壓縮 — 最近 2 輪保留原文，更早的輪次則從 500 字逐步縮減為 200 字，以節省輸入 token（使用者輪次維持原樣）。此外，當使用者詢問過去的發言（例如「你上次說過～」）時，伺服器會搜尋已儲存的實際對話，並附上日期與說話者加以引用（包含在 recalledMemories 中）；若沒有紀錄，則不會捏造，而是直接回答沒有紀錄。

LLM API（轉售）與 RIDM Memory API 的差異

同一個模型，不同的產品 — 只有前綴不同，其餘完全相同。回應中若附有 recalledMemories 與 memorySaved，代表走的是 RIDM 路徑。

程式碼範例比較

// LLM API (resale) — no memory
{
  "model": "openai/gpt-5.6-terra",
  "messages": [{ "role": "user", "content": "..." }]
}

// RIDM Memory API — with the memory engine
{
  "model": "ridm/gpt-5.6-terra",  // only the prefix differs
  "user": "user_123",              // required (keeps memory)
  "messages": [{ "role": "user", "content": "..." }]
}

// Difference in the response
// Resale: { "id": "...", "choices": [...], "usage": {...}, "costWon": 1, "costUsd": 0.00045 }
// RIDM: { "id": "...", "choices": [...], "usage": {...}, "costWon": 2, "recalledMemories": [...], "memorySaved": { "id": "turn-...", "keywords": [] } }

POST /api/v1/partners/v1/chat/completions

具備記憶的對話式 LLM 呼叫。以相同的 user/endUserId 呼叫時，會保留過去的上下文。

請求參數

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/chat/completions \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ridm/gpt-5.6-terra",
    "user": "member-1024",
    "messages": [
      { "role": "user", "content": "Can we pick up where we left off about changing jobs?" }
    ]
  }'

回應範例

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1629292800,
  "model": "ridm/gpt-5.6-terra",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 이전 대화를 기억하고 있어요..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 320,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "costWon": 45,
  "recalledMemories": [...],
  "memorySaved": { "id": "turn-1756200000000", "keywords": [] },
  "youtubeUsed": ["abc123def45"]
}

usage 中沒有 total_tokens — 回傳的是 prompt_tokens、completion_tokens、prompt_tokens_details.cached_tokens，推理模型另有 completion_tokens_details.reasoning_tokens（已包含在 completion_tokens 中）。memorySaved 為已儲存輪次的資訊物件或 null（超過上限、工具呼叫的輪次），youtubeUsed 為已插入字幕的影片 ID 陣列（不是 URL）。

串流（SSE）格式

當 stream: true 時，回應不是 OpenAI 的 chunk 格式，而是以具名的 SSE 事件傳送。因此無法用 OpenAI SDK 的串流解析器讀取 — 請自行解析 SSE（非串流回應則相容 OpenAI）。

event: chunk
data: {"delta":"안녕하세요"}

event: message_done
data: {"finish_reason":"stop","usage":{"prompt_tokens":1250,"completion_tokens":320,"prompt_tokens_details":{"cached_tokens":0}},"costWon":45,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]}}

data: [DONE]

錯誤代碼

除了共通錯誤之外，此 API 會回傳以下代碼。stream: true 時，回應開始後發生的錯誤會以 event: error（{message, code, status}）傳送。轉售模型也適用同一張表。

注意事項

• 插入 YouTube 字幕： youtube:true 時，會從最後一則訊息的 YouTube 連結擷取字幕並計入輸入 token。若無法取得字幕，對話會在不插入的情況下照常進行，回應的 youtubeUsed 會是空陣列（只有獨立的 YouTube 摘要 API 會回傳 400 且不計費）。
• 相容原始模型： model 值指定為 openai/*、google/*、anthropic/* 時，會以不含記憶功能的方式直接呼叫原始模型（成本 × 匯率 × 1.10）。
• 提示快取折扣： OpenAI 系列模型（openai/*、ridm/gpt-*）重複傳送相同的前段內容（1,024 token 以上）時，命中上游快取的輸入 token 會以輸入單價的 30% 計費。可透過回應的 usage.prompt_tokens_details.cached_tokens 與 GET /usage/logs 的 cachedTokens 確認，是否命中快取可能依上游政策而每次呼叫不同。Google 模型沒有快取，因此適用全額輸入單價。 Claude 模型也不會要求快取，因此適用全額輸入單價。
• 不適用 REPORT_ONLY_MODEL： ridm/saju-report 是無記憶的單次專用模型，無法在此端點使用（400）。

自訂個人資料（Custom Profile）

僅限 ridm/* 模型。 為每位終端使用者儲存並管理任意的欄位名稱與值。可以儲存自動擷取的欄位值、由合作夥伴直接指定值，或將特定欄位放入本輪的提示中。值會累積保存，即使結構描述變更，既有的值也會保留（soft-update）。

請求參數（POST /api/v1/partners/v1/chat/completions）

請求範例（RIDM chat）

{
  "model": "ridm/gpt-5.6-terra",
  "user": "enduser_123",
  "messages": [
    { "role": "user", "content": "Help me plan my kid's birthday party tomorrow" }
  ],
  "extractProfileFields": ["childAge", "interests", "budget", "constraints"],
  "injectProfileFields": ["name", "childAge", "interests"],
  "endUserProfile": {
    "name": "Jane Kim",
    "childAge": "7",
    "interests": "science, art"
  },
  "profileValueMaxChars": 200
}

回應中的個人資料

傳送了個人資料參數的請求，其回應（串流時為 message_done）會附上 customProfile 欄位。

"customProfile": {
  "injected": ["name", "childAge", "interests"],  // fields injected into this turn's prompt
  "stored": 4,                                     // number of fields currently stored
  "extractPending": ["budget"]                     // extraction targets that have no value yet
}

刪除 API

若要刪除特定欄位，請傳送 DELETE 請求：

DELETE /api/v1/partners/v1/profile/{endUserId}/field/{key}
X-Partner-Api-Key: your-api-key

回應：{ "success": true, "data": { "deleted": true } } — 即使是不存在的鍵或第一次出現的 endUserId，也會回傳 200 與 "deleted": false（不會建立新的終端使用者）。此 API 沒有專屬的錯誤代碼，只會回傳共通錯誤。

上限與限制

• 欄位上限： 每位終端使用者最多 100 個欄位。超過時會從最舊的欄位開始刪除。
• 值的長度： 每個欄位預設 150 字，最多 500 字。可透過 profileValueMaxChars 調整。
• 累積儲存： 以 extractProfileFields 擷取的值會累積保存，空值或 null 會略過並保留既有的值。只有透過上方的 DELETE API（或超過 100 個時依舊到新順序自動刪除）才會刪除欄位。以 endUserProfile 指定的值會覆寫擷取值。
• 值長度以請求為單位： profileValueMaxChars 不會被保存，只套用於該次請求中儲存的值。
• Soft Update： 即使結構描述（欄位名稱）變更，既有的值也會保留，並在每次呼叫時與新值合併。
• 僅限 ridm/*： 轉售模型（openai/*、google/*）會忽略個人資料。

LLM API（轉售）

轉售 openai/*、google/* 等原始 LLM 模型（無記憶，原始回應原樣傳回）。轉售模型的請求中，user、systemPrompt、recallCount、memoryCap、summaryEvery、emotion、candor 會被忽略（系統指示請以 {"role":"system"} 放進 messages），回應中也不會有記憶欄位（recalledMemories 等）。價格＝成本 × 匯率 × 1.10。

提供的模型（與 GET /api/v1/partners/v1/models 相同的清單）

• OpenAI（23 款）： openai/gpt-6-astra · openai/gpt-6-sol · openai/gpt-6-luna · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4 · openai/gpt-5.4-mini · openai/gpt-5.4-nano · openai/gpt-5.2 · openai/gpt-5.1 · openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-4.1 · openai/gpt-4.1-mini · openai/gpt-4.1-nano · openai/gpt-4o · openai/gpt-4o-mini · openai/o3 · openai/o3-mini · openai/o4-mini
• Google（3 款）： google/gemini-3.5-flash · google/gemini-3.5-flash-lite · google/gemini-3.1-pro
• Anthropic（13 款）： 請參閱下方的 Claude 模型說明
• RIDM： 上述每個模型都有在相同名稱前加上 ridm/ 前綴的記憶型模型（轉售價 × 1.3），另有八字報告專用的 ridm/saju-report（只能透過 /reading/report 呼叫）。

curl https://api.hrum.ai/api/v1/partners/v1/models \
  -H "X-Partner-Api-Key: your-api-key"

GET /api/v1/partners/v1/models 的回應 — 並非 OpenAI 的 models.list 格式。價格為每 1M token 的韓元（₩），下方數字僅為範例。Claude 模型只有在伺服器已設定時才會出現在清單中。

{
  "success": true,
  "data": {
    "models": [
      { "modelId": "openai/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1234, "output_cost_krw": 9876, "category": "base" },
      { "modelId": "ridm/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1604.2, "output_cost_krw": 12838.8, "category": "ridm" }
    ]
  }
}

此 API 沒有專屬的錯誤代碼，只會回傳共通錯誤。免費。

思考（推理）模型與 max_tokens： 使用隱藏思考（thinking/reasoning）的模型，思考 token 也會計入輸出上限。伺服器雖會加上餘裕後呼叫，但若 max_tokens 非常小（例：16），可能會以 finish_reason: "length" 回應且本文為空，上游已消耗的 token 仍會計費。建議最小值為 64 以上。適用模型：openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1 · google/gemini-3.1-pro（含加上 ridm/ 前綴的同名模型）。

思考餘裕與計費 token： 無法關閉思考的模型（openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · google/gemini-3.1-pro）與思考一律開啟的模型（anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1）（含加上 ridm/ 前綴的同名模型），為確保能取得回答，伺服器會在要求的 max_tokens 上加上思考餘裕（最多 1,500 token）後呼叫。思考 token 也以輸出單價計費，因此實際計費的輸出 token 可能大於 max_tokens（例：max_tokens 200 的請求計費 828 token — 思考 747＋本文 81）。若需嚴格限制費用上限，請使用 google/gemini-3.5-flash 這類可關閉思考的模型。

POST /api/v1/partners/v1/chat/completions

請求參數（無記憶層）

使用範例（相容 OpenAI SDK）

const client = new OpenAI({
  apiKey: 'your-float-api-key',
  baseURL: 'https://api.hrum.ai/api/v1/partners/v1',
  defaultHeaders: { 'X-Partner-Api-Key': 'your-float-api-key' }
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.6-terra',
  messages: [{ role: 'user', content: 'Hello' }]
});
// RIDM model example: model: 'ridm/gpt-5.6-terra'

回應

非串流回應為相容 OpenAI 的結構，再加上 costUsd、costWon、requestId。stream: true 並非 OpenAI 的 chunk 格式，因此無法用 OpenAI SDK 的串流解析器讀取 — 請參閱串流（SSE）格式自行解析。

{
  "id": "chatcmpl-1791452814000",
  "object": "chat.completion",
  "created": 1791452814,
  "model": "openai/gpt-5.6-terra",
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0 } },
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" }
  ],
  "costUsd": 0.000162,
  "costWon": 1,
  "requestId": "resale-..."
}

錯誤代碼與 RIDM Memory API 的錯誤表相同。轉售模型也同時適用每日支出上限（RATE_LIMITED）。

AI 八字解讀 API

由生成式 AI 分析八字，提供量身打造的運勢解讀與建議。以 token 計費，只回傳解讀結果。

POST /api/v1/partners/v1/reading

根據八字產生 AI 八字解讀。內部的提示與理論不公開。

請求參數

請求參數 — tools 選項

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Is this a good year to change jobs?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "maxLength": 600,
    "tone": "warm"
  }'

回應範例

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "usage": {
      "inputTokens": 450,
      "outputTokens": 280
    },
    "costPoints": 18
  }
}

回應欄位

錯誤代碼

除了共通錯誤之外，此 API 會回傳以下代碼：

納入項目 — 紫微斗數 · 占星 · 解夢 · 塔羅

八字 AI 中包含了八字、紫微斗數、占星、塔羅、解夢 AI。當日的日辰無須另外呼叫，就會預設反映在所有解讀中（不另收費）。以整合方式呼叫一次，就會以納入項目的計算結果為依據一起解讀；想排除的項目則以 exclude 排除。若只想呼叫需要的單一 AI，請使用 only。如果只需要計算結果，也可以透過計算型端點（/ziwei-chart · /astrology（占星全覽） · /dream · /tarot）逐一單獨呼叫相同的項目，自行打造應用程式。/reading/memory 也使用相同的欄位。

• 計費： 在既有的 token 價格（問題＋persona＋納入項目依據區塊的字數 × 0.25 作為輸入 token，再加上輸出 token）之上，每個納入的項目再加上該項目單獨端點 1 次的價格。依據區塊是每個項目 1,500 字以內的摘要。帳號中已關閉該功能或沒有價格的項目不會納入。各項目費用與單次預估範圍請見價格頁面。
• 只傳送四柱（saju）的請求沒有出生年月日，因此不會納入紫微斗數、占星（解夢、塔羅仍會納入）。
• 與 tools.astrology 的關係： 納入占星項目時，為避免重複放入同一張本命盤，會略過 tools.astrology 的星盤插入。若排除占星項目（exclude 或功能關閉），tools.astrology 會照現在的方式運作。
• 解夢安全機制： 若 dream 內容為危機表述，不會呼叫 AI，而是以 costPoints: 0 回傳求助資訊（support）。
• 功能開關： 目前為開啟狀態。若伺服器設定關閉，即使傳送 exclude、dream、tarot 也會被忽略，解讀、價格、回應都會與沒有納入項目時相同（沒有 modulesUsed、moduleFees、tarot）。

請求範例（POST /api/v1/partners/v1/reading）

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "I can't stop thinking about last night's dream. What could it mean for me right now?",
  "dream": "큰 뱀이 집 안으로 들어와 내 발 옆에 똬리를 틀었어요",
  "tarot": { "spread": "past-present-future" }
}

回應範例

{
  "success": true,
  "data": {
    "interpretation": "뱀이 집 안으로 들어와 곁에 머무는 꿈은...",
    "sajuSource": "computed",
    "modulesUsed": ["saju", "dream", "ziwei", "astro", "tarot"],
    "moduleFees": { "dream": 30, "ziwei": 50, "astro": 20, "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 3140,
      "outputTokens": 760
    },
    "costPoints": 162
  }
}

只有八字（排除其他所有項目）（POST /api/v1/partners/v1/reading）

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "Is this a good year to change jobs?",
  "exclude": ["ziwei", "astro"]
}

單獨呼叫一個 AI — only

八字 AI 中包含了八字、紫微斗數、占星、塔羅、解夢 AI。除了像上面那樣整合呼叫一次之外，也可以用 only 單獨呼叫需要的一個 AI。該 AI 只會根據自己的依據（命盤、星盤、抽出的牌、解夢候選）作答，不會放入其他項目。

• 計費： token 價格（問題＋persona＋僅該 AI 的一個依據區塊，字數 × 0.25 作為輸入 token，再加上輸出 token）＋該項目的 1 筆固定費用。各領域的單次預估價格請見價格頁面。
• 不可與 exclude 同時使用： 兩者都傳送時回傳 400 ONLY_WITH_EXCLUDE。缺少該 AI 所需的輸入時回傳 400 ONLY_REQUIRES_INPUT，帳號中已關閉該功能時回傳 400 ONLY_DOMAIN_UNAVAILABLE — 不會改以八字解讀代替回答。若為無法計算命盤、星盤的日期，則回傳 400 ONLY_INPUT_INVALID。
• tarot、dream 不需要出生年月日。 不必傳送 birth、saju，只要傳送問題與牌（或夢境內容）即可。only 不是 saju 時不會使用八字，因此回應中沒有 sajuSource。
• 功能開關： 與納入項目適用相同的伺服器設定，目前為開啟狀態。設定關閉時，only 會被忽略，運作方式與既有的八字解讀相同。

請求範例 — 僅塔羅 AI（POST /api/v1/partners/v1/reading）

{
  "question": "Should I keep pushing ahead with the job change I'm preparing?",
  "only": "tarot",
  "tarot": { "spread": "past-present-future" }
}

回應範例

{
  "success": true,
  "data": {
    "interpretation": "과거 자리의 완드의 10 역방향은 오래 짊어진 짐을...",
    "only": "tarot",
    "modulesUsed": ["tarot"],
    "moduleFees": { "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 1180,
      "outputTokens": 720
    },
    "costPoints": 37
  }
}

注意事項

• 只回傳解讀結果： 回應中只包含產生的運勢解讀文字，不會公開內部提示或八字理論。
• candorApplied： 只有在以 t 傳送 candor 時，回應才會附上實際套用的直言度（t | f）。/reading/memory 也相同（直言度（暫定名稱））。
• 計費依據： 輸入＝（question＋persona 的字數）× 0.25 token（＋在 /reading 中插入的 YouTube 字幕字數 × 0.25），輸出＝實際的 completion token。八字插入與系統提示不計費，usage.inputTokens 僅供參考。開啟納入項目（今日運勢 · 紫微斗數 · 占星 · 解夢 · 塔羅）時，會加上其依據區塊與各項目的固定費用。costPoints 為實際扣款金額。
• 回應語言： 非韓文的問題會以與問題相同的語言回答。
• 出生時間不詳： 省略 hour 時，會排除時柱，以年、月、日三柱為準進行解讀。

AI 八字解讀、記憶 API

為每位終端使用者託管對話記憶，在使用者再次造訪時延續過去的上下文進行解讀，提供個人化且持續的諮詢體驗。價格為 AI 八字解讀 token 單價的 1.3 倍（每 1M token：輸入 3,754 韓元、輸出 30,030 韓元 — 解讀為輸入 2,888 韓元、輸出 23,100 韓元，VAT 另計）。

POST /api/v1/partners/v1/reading/memory

根據每位終端使用者的記憶產生 AI 八字解讀。

請求參數

請求參數 — tools 選項

回應範例

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "memory": {
      "used": true,
      "summaryInjected": false,
      "notesInjected": 2,
      "tags": ["직장"],
      "overheadTokens": 120
    },
    "usage": {
      "inputTokens": 750,
      "outputTokens": 380
    },
    "costPoints": 36,
    "toolsUsed": ["memory"]
  }
}

其他回應欄位（sajuMismatch、toolsSkipped、filesUsed）與 AI 八字解讀 API 相同；自動回想的文件會放在 filesRecalled，tools.emotion: true 時則會附上 emotion。計費依據（YouTube 除外）也與解讀 API 相同。

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/memory \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "member-1024",
    "question": "About the job change we talked about last time: is next month a good time to make the move?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" }
  }'

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳以下代碼：

記憶管理 API

AI 八字解讀記憶型（POST /reading/memory）與 RIDM 聊天（ridm/* 模型的 user）使用同一個終端使用者記憶儲存區。下方路徑中的 {endUserId} 就是當時傳送的值（例如將聊天按工作階段區分時，就是 memberId:chatId 這類完整的鍵）。

請求、回應範例

# Get stored memory
curl https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "summary": "이직을 고민 중이며 다음 달 면접을 앞두고 있다...",
    "metaSummary": "...",
    "tags": ["이직", "면접"],
    "profile": null,
    "concerns": ["..."],
    "facts": []
  }
}

# Message list (oldest first)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/messages?limit=2&offset=0" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "messages": [
      { "id": "...", "role": "user", "content": "이직 고민이 있어요", "tags": ["이직"], "createdAt": "2026-10-11T09:00:00.000Z" },
      { "id": "...", "role": "assistant", "content": "...", "tags": [], "createdAt": "2026-10-11T09:00:04.000Z" }
    ],
    "offset": 0,
    "limit": 2,
    "total": 18
  }
}

# Tag search (tags as stored: 이직 = job change, 면접 = interview)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/search?endUserId=member-1024&tags=이직,면접" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "query": { "tags": ["이직", "면접"] },
    "results": [
      { "id": "...", "summary": "다음 달 면접 일정을 이야기함", "level": 0, "tags": ["면접"], "createdAt": "2026-10-11T09:00:00.000Z" }
    ]
  }
}

# Save a conversation (no AI generation)
curl -X POST https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/turns \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I'\''m worried about my interview next month" },
      { "role": "assistant", "content": "You'\''ve prepared well. You'\''ll do fine." }
    ],
    "summary": "Call about feeling anxious before next month'\''s interview",
    "tags": ["interview"]
  }'

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "saved": 2,
    "summarySaved": true
  }
}

# Delete everything (memory + uploaded files) — 204, no body
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳以下代碼：

注意事項

• 1.3 倍單價： 由於託管記憶，輸入/輸出 token 單價為 AI 八字解讀的 1.3 倍（每 1M token：輸入 3,754 韓元、輸出 30,030 韓元，VAT 另計）。
• endUserId 必填： 每位終端使用者都必須有唯一的 ID，以相同 ID 呼叫時會保留過去的上下文。
• 記憶保存： 已儲存的記憶會保存到明確刪除為止。

八字報告 API

不需要提問，按一下按鈕就能一次取得所有八字解讀，從總評、財運、感情到大運。這是與對話型（reading）分開、單次付款的商品。預設使用專用模型 ridm/saju-report（RIDM 自家的報告特化模型 — 由於是單次商品，不搭載記憶）。解讀 API 的回應上限為 2,000 字 — 若需要更長的詳細解說（最多 12 節，約 6,000 字），請使用此報告 API。

POST /api/v1/partners/v1/reading/report

輸入出生年月日（或八字），即可取得依章節分段的 Markdown 八字報告。

請求參數

報告一律以韓文撰寫。傳送 speed、tools、lang、question 等上表中沒有的欄位時，會以 400 拒絕。

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/report \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "sections": ["총평", "재물운", "연애·인연"]
  }'

回應

{
  "success": true,
  "data": {
    "report": "## 총평\n...",        // full Markdown, section by section
    "sections": ["총평", "..."],
    "sajuSource": "computed",
    "usage": { "inputTokens": 5756, "outputTokens": 2019 },
    "costPoints": 77,
    "model": "ridm/saju-report"
    // "candorApplied": "t"  — only when candor was sent as t (t | f)
  }
}

• 八字插入免費： 萬年曆計算、插入與系統提示不計費。輸入只依 persona 長度計費，輸出則依實際使用的 token 計費。
• 實測費用： 預設 8 個章節（約 3,000 字）的報告 1 次約 85P（以輸出 ₩38,077/1M 為準）。
• 重試會再次計費。 收到回應後若想以相同輸入重複使用，請在用戶端儲存（冪等性）。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳以下代碼：

YouTube 摘要 API

擷取 YouTube 影片的字幕，提供摘要與 Q&A 分析。沒有字幕時回傳 400 錯誤（不計費）。

POST /api/v1/partners/v1/youtube/summary

請求參數

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/youtube/summary \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxLength": 1000 }'

回應範例

{
  "success": true,
  "data": {
    "summary": "## 0:00~1:30 오프닝\n영상 제목 설명...\n\n## 1:30~5:00 본론\n...",
    "video": {
      "videoId": "dQw4w9WgXcQ",
      "title": "Video Title",
      "channel": "Channel Name"
    },
    "transcriptSource": "supadata",
    "usage": {
      "promptTokens": 7059,
      "completionTokens": 1384
    },
    "costPoints": 51,
    "model": "ridm/gpt-5.6-terra"
  }
}

注意事項

• 必須有字幕： 沒有字幕時回傳 TRANSCRIPT_UNAVAILABLE 400（不計費）。
• 錯誤： 錯誤的 URL、ID 回傳 400 INVALID_YOUTUBE_URL / 摘要產生失敗回傳 400 LLM_GENERATION_FAILED / 餘額不足回傳 402 INSUFFICIENT_BALANCE。
• 計費： 以 token 計費。依使用模型（預設 ridm/gpt-5.6-terra）的轉售價原價（成本 × 1.1）計算 — 由於沒有記憶層，不會套用 RIDM Memory 單價（× 1.3）。costPoints＝無條件進位（輸入 token × 輸入單價＋輸出 token × 輸出單價），單價以 1M token 為準（VAT 另計）。
• 實測費用： 20–30 分鐘的影片 1 次約 60P（含 token）。
• 與解讀串接： 在 AI 八字解讀 API（/reading）中，可用 tools: { "youtube": true } 插入問題中連結的字幕（最上層的 youtube 欄位會被忽略）。YouTube 插入僅支援 /reading（/reading/memory 尚未支援）。傳送到 /reading/memory 時不會取得字幕，而是在 toolsSkipped 中以 {"tool": "youtube", "reason": "unavailable"} 告知。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳以下代碼：

開啟與關閉功能

YouTube 摘要 API 可依合作夥伴帳號及請求單位選擇啟用。在主控台的「功能設定」中管理全域啟用狀態；chat 需明確指定最上層的 youtube:true，reading 則需明確指定 tools: { "youtube": true }，以按請求啟用。

• 全域停用： 回應 403 { code: 'FEATURE_DISABLED', feature: 'youtube' }
• 請求單位： 未指定 youtube:true 或為 false＝不插入 YouTube 內容

文件處理 API

可上傳 PDF、Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）、CSV、純文字、Markdown、Hangul（.hwpx）文件，並以 AI 分析後存入以上下文為基礎的知識庫。文件會自動擷取內容；啟用「AI 分析」選項時，會將文件按上下文切分，並為每個區段產生摘要與搜尋標籤後儲存。

支援格式與限制

端點

上傳檔案

POST /api/v1/partners/v1/files

以 Multipart form 格式上傳檔案。

請求欄位

cURL 範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/files \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "endUserId=user_123" \
  -F "analyze=true"

回應範例

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    "originalName": "sample.pdf",
    "mime": "application/pdf",
    "size": 125000,
    "textLength": 8942,
    "charsCapped": false,
    "textPreview": "1장. 개요 ...",
    "summary": "문서 전체 요약...",
    "context": "문서 전체 요약...",
    "status": "analyzed",
    "analysisStatus": "analyzed",
    "analyzeRequested": true,
    "endUserId": "user_123",
    "usage": { "inputTokens": 3100, "outputTokens": 420, "costWon": 1 },
    "totalChunks": 3,
    "createdAt": "2026-08-26T12:34:56Z"
  }
}

清單、詳細資料、刪除

# List — newest first, limit 1–100 (default 20)
curl "https://api.hrum.ai/api/v1/partners/v1/files?endUserId=user_123&limit=20&offset=0" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "files": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "sample.pdf", "status": "analyzed", ... } ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

# Details — upload response fields + extractedText + chunks
curl https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    ...,
    "extractedText": "1장. 개요 ...",
    "chunks": [
      { "id": "...", "chunkIndex": 0, "context": "1장 요약...", "tags": ["개요"], "textLength": 2980 }
    ]
  }
}

# Delete
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{ "success": true, "data": { "deleted": true } }

與 Chat 及解讀串接

明確附加： 在 Chat completions 或 AI 解讀請求中，可用 fileIds 參數插入最多 5 份文件。已分析的檔案會插入文件摘要（最多 500 字）與原文文字，未分析的檔案則插入原文文字（原文限制為每個檔案 40,000 字 / 合計 80,000 字，不插入子區塊）。插入的文件會附加到最後一則使用者訊息，並計入輸入 token。轉售模型只支援以 fileIds 明確插入。

自動回想（僅限 ridm/*）： 在 ridm/* chat 與 reading-memory 模型中，會自動搜尋並插入與使用者問題標籤重疊的已分析檔案（僅在未明確指定 fileIds 時）。回應中會以 filesRecalled 陣列顯示回想到的檔案 ID。

Chat 請求範例

{
  "model": "ridm/gpt-5.6-terra",
  "messages": [
    { "role": "user", "content": "Can you summarize the main points of this document?" }
  ],
  "fileIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "user": "user_123"
}

回應範例

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": { "content": "문서의 주요 내용은..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2500, "completion_tokens": 150 },
  "filesUsed": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

filesRecalled 只有在有自動回想的檔案時才會附上（為空時省略）。

價格與計費

• 上傳與擷取： 免費（文字擷取的 token 不計費）
• AI 分析（analyze=true）： 依邊界偵測＋各區段摘要＋整體摘要實際使用的 token 量，以分析模型單價計費。同步 ≤30,000 字，非同步 >30,000 字（status：analyzing）
• Chat 插入： 文件文字會計為輸入 token，計費方式與一般 chat 請求相同
• 紀錄： 可在主控台的使用紀錄中，以 file_upload（免費）、file_analyze（付費，依實際使用 token）分類確認

開啟與關閉功能

文件處理功能可在合作夥伴帳號層級啟用或停用。在主控台的「功能設定」中管理，停用時所有檔案請求都會回傳 403。

• 全域停用： 回應 403 { code: 'FEATURE_DISABLED', feature: 'files' }
• 請求單位： 未指定 fileIds＝不插入文件（正常處理）

分析狀態與區塊

GET /api/v1/partners/v1/files/:id 的回應包含 analysisStatus、extractedText、chunks。只有在分析完成且 totalChunks 為 2 以上時，chunks 才會是陣列（每個區塊：chunkIndex、context（摘要）、tags 最多 10 個），其他情況則為 null。上傳回應中沒有 chunks。

注意事項

• 格式驗證： 不支援的格式會回傳 400 { code: 'INVALID_FILE_TYPE' }
• 其他錯誤： 缺少檔案回傳 400 FILE_NOT_PROVIDED / 超過 10MB 回傳 400 FILE_TOO_LARGE / 不存在的檔案回傳 404 FILE_NOT_FOUND / :id 不是 UUID 時回傳 400
• 分析必填項目： analyze=true 時若沒有 endUserId，會回傳 400 { code: 'END_USER_REQUIRED' }
• 擷取失敗： 擷取文件時發生錯誤會回傳 422 { code: 'EXTRACTION_FAILED' }
• 餘額確認： 分析請求前會檢查合作夥伴的點數是否足夠。不足時回傳 402
• 自動存入知識庫： analyze=true 時，各區段的摘要與標籤會自動儲存到知識庫，之後成為 auto-recall 的對象。指定 endUserId 時，也會加入該使用者的記憶層。
• 重新上傳＝新檔案： 每次上傳都會建立新檔案（新 id），analyze=true 時會再次分析並計費。相同的文件請只上傳一次，並以 fileIds 重複使用取得的 id。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳以下代碼：

情緒狀態分析（Emotion）

搭配 Chat API 的摘要週期，分析使用者與 AI 的情緒狀態。不會另外呼叫 LLM，只是在摘要提示詞中加入情緒分析區塊，因此不會額外計費。僅支援 ridm/* 模型。

總覽

啟用條件：

1. 全域：partner_emotion_enabled ✓
2. 合作夥伴：在主控台的功能設定中啟用「情緒狀態分析」
3. 請求：明確指定 emotion: true
4. 模型：僅支援 ridm/* 系列

摘要週期（summaryEvery）

情緒分析會在每個摘要週期自動執行。可用 summaryEvery 參數調整週期（預設值：5，範圍：1–20）。

• summaryEvery=1：幾乎每一輪都更新情緒（摘要在回應之後以非同步方式執行）
• summaryEvery=5：每 5 輪（建議）
• summaryEvery=20：每 20 輪（更新最少）
• 不論週期長短，摘要與情緒週期都不會向合作夥伴計費。

請求參數

請求範例

{
  "model": "ridm/gpt-5.6-terra",
  "user": "user_123",
  "messages": [
    { "role": "user", "content": "Today was a rough day..." }
  ],
  "emotion": true,
  "summaryEvery": 3
}

回應欄位

回應範例

{
  "id": "chatcmpl-xyz",
  "choices": [{
    "message": { "content": "오늘 하루가 힘들었군요..." },
    "finish_reason": "stop"
  }],
  "emotion": {
    "user": {
      "type10": "sad",
      "tone": "warm",
      "distribution6": {"joy": 100, "sadness": 600, "anger": 50, "fear": 100, "disgust": 50, "surprise": 0}
    },
    "assistant": {
      "distribution6": {"joy": 200, "sadness": 100, "anger": 0, "fear": 0, "disgust": 0, "surprise": 0}
    },
    "trend": "stable",
    "updatedAt": "2026-08-26T12:34:56Z",
    "turnsSinceUpdate": 0
  },
  "usage": {...}
}

分布欄位說明（distribution6）

趨勢判定（trend）

• improving：非正向情緒（sadness+anger+fear+disgust）減少 50 以上
• stable：變化未滿 50
• declining：非正向情緒增加 50 以上
• null：沒有前一個週期的資料

串流回應範例（SSE）

在串流模式（stream: true）下，情緒狀態會包含在 event: message_done SSE 事件的資料中。

event: message_done
data: {"finish_reason":"stop","usage":{...},"costWon":2,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]},"emotion":{"user":{"type10":"concerned","tone":"warm","distribution6":{...}},"assistant":{...},"trend":"stable","updatedAt":"2026-08-26T12:34:56Z","turnsSinceUpdate":0}}

data: [DONE]

費用說明

• 不另外計費：情緒分析包含在摘要週期的提示詞中進行，摘要與情緒週期的 token 不會向合作夥伴計費。計費的只有聊天輪次本身的輸入與輸出 token。

注意事項

• 第一個週期之前：在第一個摘要週期執行之前不會有 emotion 欄位（屬正常行為）。
• 功能關閉時：請求為 emotion: true，但全域或合作夥伴的功能設定未啟用時，回傳 403 { code: 'FEATURE_DISABLED', feature: 'emotion' }（與 YouTube、文件處理相同）。未傳送 emotion 或為 false 時，只會省略該欄位。
• 僅支援 ridm/* 模型。已開啟情緒功能的帳號，轉售（openai/*、google/*）請求中的 emotion 欄位會被忽略；已關閉的帳號則不論模型為何，emotion:true 都會回傳 403 FEATURE_DISABLED。
• 串流：在串流回應中，emotion 會包含在 message_done SSE 事件裡。

八字圖片 API

產生呈現八字五行與能量的 AI 藝術圖。以 base64 編碼的 PNG 格式回傳，固定計費 ₩200。

POST /api/v1/partners/v1/image

依據出生年月日產生八字五行圖片。

請求參數

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/image \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female", "style": "portrait" }'

回應範例

{
  "success": true,
  "data": {
    "imageDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "costPoints": 200
  }
}

注意事項

• 固定價格：每次產生圖片計費 ₩200。
• 產生時間：產生圖片約需 20~30 秒，請將逾時時間設定得充裕一些。
• Base64 編碼：回傳的 imageDataUri 是以 base64 編碼的 PNG 圖片，可直接用於 HTML <img src="{imageDataUri}"> 標籤。
• 風格：background（背景藝術）、icon（極簡圖示）、portrait（肖像插畫）只改變氛圍。所有風格的尺寸都相同（預設 1024×1024 正方形）。
• 逾時：若上游未在 80 秒內回傳圖片，會回傳 504 IMAGE_UPSTREAM_TIMEOUT 且不計費。請重新嘗試。
• 出生時間不明：省略 hour 時，會去掉時柱，以年、月、日三柱為基準解讀。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

圖片生成 API（模型轉售）

POST /api/v1/partners/v1/images/generations

以與 OpenAI Images API 相同的格式，用一把金鑰呼叫 GPT-Image 與 Nano Banana 模型。每個模型、解析度、品質都有固定的每張價格，表中金額會直接扣除（產生張數 × 每張價格）。提示詞的輸入 token 費用已包含在每張價格中，不會另外加收。

請求參數

對 GPT-Image 傳送 aspect_ratio、resolution，或請求模型不支援的解析度時，會以 400 INVALID_PARAMETER 拒絕，且不計費。

其他錯誤：MODEL_NOT_FOUND、INVALID_MODEL（400，不存在的模型）、INVALID_PROMPT（400，上游拒絕提示詞）、UPSTREAM_ERROR、RATE_LIMITED（目前為 HTTP 400，本文 status 為 429）、INSUFFICIENT_BALANCE（402）。

每張價格（₩，VAT 另計）

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "prompt": "A serene mountain landscape at sunset",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

回應範例

{
  "created": 1791452814,
  "data": [ { "b64_json": "iVBORw0KGgo..." } ],
  "costWon": 225,
  "requestId": "..."
}

• GPT-Image 與 Google 直接模型以 b64_json 回傳圖片，FAL 模型以 url 回傳。
• costWon = 每張價格 × 實際產生的張數。若上游一張圖片都沒有回傳，則不計費。
• GPT-Image 回應中的 usage（token 數）僅供參考，不用於計價。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

錯誤回應與其他 API 相同，為 {"success": false, ...} 格式（只有成功回應不會被包裝）。

耗時較長的產生：非同步回應（202，選用）

高解析度或多張的請求可能超過 1 分鐘。在請求標頭加入 Prefer: respond-async 後，若 60 秒內結果尚未就緒，伺服器不會佔住連線，而是回傳 202 Accepted 與工作 ID，並在伺服器上繼續產生，最長 240 秒。若在 60 秒內完成，會收到與現在相同的 200 回應。不送這個標頭時，行為與現在完全相同（80 秒內未完成時回傳 504 IMAGE_UPSTREAM_TIMEOUT，不計費），請只從能處理 202 的用戶端送出此標頭。

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"model": "google/nano-banana-pro", "prompt": "...", "resolution": "4K"}'

HTTP/1.1 202 Accepted
Location: /api/v1/partners/v1/jobs/imgjob_3f2a...
Retry-After: 5
Preference-Applied: respond-async

{
  "id": "imgjob_3f2a...",
  "object": "image.job",
  "status": "pending",
  "pollUrl": "/api/v1/partners/v1/jobs/imgjob_3f2a...",
  "retryAfter": 5,
  "createdAt": "2026-10-12T03:00:00.000Z",
  "expiresAt": "2026-10-13T03:00:00.000Z"
}

GET /api/v1/partners/v1/jobs/{id}

請使用同一把 API 金鑰（X-Partner-Api-Key），每隔 Retry-After 秒查詢一次。查詢免費，不計入每日請求上限。但每把 API 金鑰每 2 秒最多 1 次，查詢更頻繁時會收到 429 IMAGE_JOB_POLL_RATE_LIMITED 與 Retry-After（秒）。回應為 HTTP 200，狀態以本文的 status 區分。

• 計費：只在結果就緒的那一刻扣除一次。等待期間會先從餘額預留預估金額，若失敗或逾時，預留會解除且不計費。查詢多次也不會重複計費。
• 保存期限：結果與錯誤可在建立工作後 24 小時內查詢，之後即刪除（之後回傳 404）。若圖片為 b64_json，查詢回應也會同樣龐大（每張數 MB），收到後請立即儲存。若整體結果超過 16MB，將不會保存，並以 IMAGE_JOB_RESULT_TOO_LARGE 判定失敗（不計費），請減少張數（n）或解析度。
• 其他合作夥伴的工作 ID、不存在的 ID、超過保存期限的 ID，一律回傳相同的 404 IMAGE_JOB_NOT_FOUND。

萬年曆 API

POST /api/v1/partners/v1/manseryeok

包含八字特質（Saju Identity）：回應末尾的 identity 欄位會一併提供三災、神煞、空亡、通根、季節強弱、大運／流年時間軸、八字 MBTI（不另外收費，計算失敗時為 null）。

計算命盤（原局）四柱（年、月、日、時）的天干、地支、漢字、五行、十神、藏干、納音、十二長生、神煞。以節氣為基準精確計算，從 命盤分析（用神、扶抑、調候用神、身強弱、清濁、通關、病藥、五行變數）→ 10 步大運（含目前大運、干支合沖刑害）→ 5 年流年（逐年等級、關係、解讀）→ 格局、詳細解讀 → 十干論、季節狀態、空亡、虛字、飛合、暗祿，以頂層基本 30 個欄位 + 選用欄位（含子欄位共 200 個以上）提供完整的八字解讀。出生時間不明時，只有時柱（wonkuk.hour）與需要實際時刻的 trueSolarTime 為 null，用神、格局、身強弱等分析欄位仍會以年、月、日三柱（6 字）為基準計算後照常提供（birthHour.basis: "three_pillars"）。

請求參數

回應欄位（基本 30 個 + 選用欄位）

PillarFull 結構（各柱的子欄位）

回應中 wonkuk.year、wonkuk.month、wonkuk.day、wonkuk.hour 各自具有的欄位：

DaeunPeriod 結構（各步大運）

SeunYear 結構（流年各年）

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2000, "month": 1, "day": 15, "hour": 14, "minute": 30,
    "gender": "male", "calendar": "solar", "timezone": "Asia/Seoul"
  }'

回應範例（節錄：2000-01-15 14:30 男性）

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": {
        "stem": "기", "branch": "묘", "stemHanja": "己", "branchHanja": "卯",
        "ohaeng": "토", "stemSipsin": "정관", "branchSipsin": "상관",
        "jijanggan": ["갑", "을"], "chunghyung": [], "hapPosition": ["半合(반합)"],
        "ungSung": "사", "napEum": "성두토",
        "majorSinsal": ["장성살"],
        "minorSinsal": ["천을귀인", "귀문관살", "원진살", "현침살", "육해살"]
      },
      "month": { ... },
      "day": { ... },
      "hour": { ... }
    },
    "trueSolarTime": null,
    "ohaengBalance": { "목": 1, "화": 2, "토": 3, "금": 1, "수": 1 },
    "yongshin": "수",
    "johuYongshin": "화",
    "yongshinDetail": {
      "method": "억부",
      "primary": "수",
      "secondary": ["금"],
      "reasoning": ["일간 임(수) 신약", "신약 + root 있음(8) → 비겁(수)"],
      "shin": { "yongshin": "수", "huishin": "금", "gishin": "토", "gushin": "화", "hanshin": "목" },
      "favorable_sipsin": ["편인", "정인", "비견", "겁재"],
      "unfavorable_sipsin": ["편관", "정관", "편재", "정재", "식신", "상관"],
      "element_states": { "목": { "count": 1, "state": "lack", "effect": "neutral" }, "...": "5오행" }
    },
    "eokbuYongshin": "수",
    "ilganSummary": "壬水 — 큰 바다의 기운. 지혜롭고 포용력이 넓어요.",
    "daeun": [
      {
        "startAge": 3, "endAge": 13,
        "stem": "병", "branch": "자", "stemHanja": "丙", "branchHanja": "子",
        "ohaeng": "화", "isCurrent": false,
        "stemSipsin": "편재", "branchSipsin": "겁재",
        "sinsal": ["년살", "장성살"]
      },
      {
        "startAge": 13, "endAge": 23,
        "stem": "을", "branch": "해", "stemHanja": "乙", "branchHanja": "亥",
        "ohaeng": "목", "isCurrent": false,
        "stemSipsin": "상관", "branchSipsin": "비견",
        "sinsal": ["지살", "망신살"]
      },
      {
        "startAge": 23, "endAge": 33,
        "stem": "갑", "branch": "술", "stemHanja": "甲", "branchHanja": "戌",
        "ohaeng": "목", "isCurrent": true,
        "stemSipsin": "식신", "branchSipsin": "편관",
        "sinsal": ["천살", "월살"]
      }
      // … cycles 4–10 (startAge 33–93) omitted — the actual response has 10
    ],
    "seun": [
      // 2024 and 2025 entries omitted
      {
        "year": 2026, "stem": "병", "branch": "오", "stemHanja": "丙", "branchHanja": "午",
        "ohaeng": "화", "isCurrent": true, "grade": "good",
        "relations": [
          { "type": "해", "target": "월주", "description": "오-축 해" },
          { "type": "육합", "target": "시주", "description": "오-미 육합" }
        ],
        "summary": "전체적으로 순조로운 흐름이 예상돼요. (해, 육합 작용)",
        "sinsal": ["육해살", "재살"]
      }
      // 2027 and 2028 entries omitted — the actual response has 5: two years either side of this year
    ],
    "branchRelations": [
      { "type": "沖(충)", "pillars": ["축", "미"], "description": "丑未沖 (축미충)" },
      { "type": "半合(반합)", "pillars": ["묘", "미"], "description": "卯未合 (묘미합)" }
    ],
    "gongmang": ["술", "해"],
    "cheonEulGwiIn": ["묘"],
    "wolryeong": "축",
    "daeunNumber": 3,
    "daeunDirection": "역행",
    "gyeokguk": {
      "name": "정관격",
      "summary": "질서·명예·합리"
    },
    "gyeokgukDetail": { ... },
    "cheonganDetail": { ... },
    "hapChungReport": { ... },
    "heojaReport": { ... },
    "gongmangDetail": { ... },
    "ohaengByeonsuHits": [
      {
        "key": "to_wang_deuk_mok",
        "subject": "土", "target": "木",
        "formula_idiom": "방능소통(方能疏通)",
        "description": "토가 왕성한데 목을 얻으면 소통이 된다",
        "category": "wang_geuk_sunwha"
      },
      {
        "key": "gang_to_deuk_geum",
        "subject": "土", "target": "金",
        "formula_idiom": "방제기해(方制其害)",
        "description": "강한 토가 금을 얻으면 그 피해를 막는다",
        "category": "gang_seolgi_sunwha"
      }
    ],
    "strength": {
      "dayMaster": "임",
      "score": -66,
      "result": "신약",
      "level": "중약",
      "breakdown": { "season": -30, "support": 8, "control": -38, "hidden": -9, "root": 8 },
      "root": { "rooted": true, "rootScore": 8 }
    },
    "jeongtak": {
      "verdict": "탁",
      "reasons": ["파괴 십신 2개 감지", "용신 금 생 ✓", "일주 신약"],
      "severity": "극탁"
    },
    "tonggwan": { ... },
    "byeongyak": { ... },
    "countryCodeUsed": null,
    "identity": {
      "rooting_hints": { ... }, "season_strength_hint": { ... }, "sinsal_list": [ ... ],
      "gongmang": { ... }, "samjae": { ... }, "timeline": { ... },
      "mbti_inference": { ... }, "coherence": { ... }
    },
    "ohaengDeficient": []
  }
}

此範例是在 2026 年呼叫的結果，因此 daeun[].isCurrent、seun 的年份會依呼叫年份而不同。{ ... } 與 // 行代表省略。此範例是未傳送地點的請求，因此 trueSolarTime 為 null。在同一請求加上 "country": "KR"（或座標）後，trueSolarTime 會帶入校正結果（"basis": "country"），countryCodeUsed 會變成 "KR"。校正結果的格式請參閱下方注意事項中的農曆輸入範例。

注意事項

• 回應內容複雜：萬年曆回應不只包含命盤，還有大運、流年、格局、神煞等詳細資訊。請只選用需要的欄位。
• 選用欄位：出生時間不明的約定：hour、minute 可以省略。省略 hour 時，不會假設為正午，而是去掉時柱。回應會有以下差異。
  • wonkuk.hour = null、trueSolarTime = null
  • ohaengBalance = 以年、月、日三柱（天干＋地支 6 字）為基準重新計算
  • branchRelations、cheonEulGwiIn = 只保留僅憑三柱地支即可成立的項目
  • 頂層新增 birthHour：{ known: false, hourPillar: null, basis: "three_pillars", excludedFields: [], note }。分析欄位（yongshin、strength、gyeokguk、hapChungReport、ilganSummary、seun 等）不會被移除，而是以年、月、日三柱（6 字）為基準計算後回傳（依字數而定的門檻值也換算為 6 字基準）。這不是假設正午的參考值，而是只用三柱算出的值
  • 判斷是否不明請使用 birthHour.known，不要用 excludedFields.length 判斷。此陣列現在一律為空，只為了相容舊版用戶端而保留
  • 未帶 hour 而送出的 minute 會被忽略（只有在有 hour 時才是 minute ?? 0）
  • 有傳送 hour 的請求沒有 birthHour 欄位，計算結果也與以往相同（2026-10-10 起附加的 identity、ohaengDeficient 除外）。一向都傳送 hour 的既有用戶端不受影響。若用戶端是依照短暫存在過的「省略時以正午計算」行為所製作，請確認 birthHour.known === false，並將時柱欄位顯示為「不明」。strength、gyeokguk 等一律以三柱基準值回傳（2026-09-16 以前會被移除）。諮詢類 API（/reading、/reading/memory、/reading/report）也依相同規則，將三柱基準值傳給模型
• 韓文欄位名稱：所有欄位名稱（天干、地支、五行等）皆以韓文標示。即使傳送 lang，欄位名稱也不會改變，只會翻譯值（用神、日干說明、大運方向、神煞名稱等）。天干、地支、五行代碼（stem、branch、ohaeng）與 ohaengBalance 的鍵在所有語言中都維持韓文。完整清單請參閱有效值 > 與語言無關的代碼值。
• 新增選項全部為選填（2026-10-08）：若完全不傳送 lang、calendar、isLeapMonth、birthLatitude、birthLongitude、country、zaSiRule、birthTimePrecision，計算結果與以往相同。但自 2026-10-10 起，回應末尾一律會加上 identity、ohaengDeficient（既有鍵的值與順序不變）。價格也維持 ₩50/次。
• 變更（2026-10-12）：農曆轉換基準改為韓國天文研究院（KASI）資料，部分日期的結果有所變動。不存在的閏月不會轉成平月，而是回傳 400 INVALID_LUNAR_DATE。
• 農曆輸入：以 calendar: "lunar" 傳送時，回應頂層會附上轉換明細 lunarInput。真太陽時校正結果會放在 trueSolarTime。引擎實際輸出範例（農曆 1990-07-15 14:30，釜山座標，lang: "en"）：

  {
    "year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30,
    "timezone": "Asia/Seoul", "gender": "male",
    "calendar": "lunar", "birthLatitude": 35.1796, "birthLongitude": 129.0756,
    "lang": "en"
  }
  →
  "lunarInput": {
    "calendar": "lunar", "lunarDate": "1990-07-15", "isLeapMonth": false,
    "leapMonthApplied": false, "solarDate": "1990-09-03"
  },
  "trueSolarTime": {
    "originalLocal": "14:30", "correctedLocal": "14:07",
    "longitudeCorrection": -23.6976, "equationOfTime": 0.3241,
    "totalCorrectionMinutes": -23.4, "dayShift": 0, "dstApplied": false,
    "basis": "coords", ...
  },
  "ilganSummary": "辛 Metal — Jewel energy. Sharp intellect and refined aesthetic sense.",
  "daeunDirection": "Forward"

• 輸入錯誤：不存在的農曆日期（例：只到 29 日的月份的 30 日）回傳 400 INVALID_LUNAR_DATE，只傳送緯度／經度其中之一的請求回傳 400 INVALID_LOCATION，都不計費。缺少 timezone 等格式錯誤也回傳 400（不計費）。

錯誤代碼

除了共通錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "topic": "career", "lang": "ko"
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          { "component": "ilgan_wolji", "key": "임_신", "text": "..." },
          { "component": "ilgan_strength", "key": "임_신강", "text": "..." },
          { "component": "ilgan_yongshin", "key": "임_화", "text": "..." },
          { "component": "ohaeng_state", "key": "목_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "토_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "수_lack", "text": "..." },
          { "component": "top_sipsin", "key": "인성", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" }
  }
}

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "birthLatitude": 37.5665, "birthLongitude": 126.978,
  "topic": "career", "lang": "ko",
  "layers": ["astro", "ziwei"]
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          ...
          { "component": "top_sipsin", "key": "인성", "text": "..." },
          { "component": "astro_sun", "key": "vir", "text": "...", "label": "별자리로 보면" },
          { "component": "astro_moon", "key": "pis", "text": "..." },
          { "component": "astro_asc", "key": "sag", "text": "..." },
          { "component": "ziwei_ming", "key": "tt_jm", "text": "...", "label": "자미두수로 보면" },
          { "component": "ziwei_palace", "key": "cr_tj", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" },
    "missingSections": 0,
    "layers": {
      "astro": { "included": true, "costWon": 20, "note": null },
      "ziwei": { "included": true, "costWon": 20, "note": null }
    }
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30,
  "gender": "female", "referenceDate": "2026-10-08", "lang": "ko"
}

{
  "success": true,
  "data": {
    "engineVersion": 1,
    "lang": "ko",
    "referenceDate": "2026-10-08",
    "clock": {
      "inputSolarDate": "1990-05-15", "inputTime": "14:30",
      "correctedSolarDate": "1990-05-15", "correctedTime": "14:30",
      "correctionMinutes": 0, "dstApplied": false, "basis": null,
      "hourBranch": { "key": "wei", "label": "미" }
    },
    "chart": {
      "engine": { "name": "iztro", "version": "2.6.1", "config": { ... } },
      "solarDate": "1990-05-15",
      "lunarDate": { "year": 1990, "month": 4, "day": 21, "isLeapMonth": false },
      "yearGanzhi": "경오",
      "yearBasisNote": null,
      "fiveElementsClass": { "key": "earth5", "label": "토오국" },
      "soulPalaceBranch": { "key": "xu", "label": "술" },
      "bodyPalaceBranch": { "key": "zi", "label": "자" },
      "palaces": [
        ...,
        {
          "key": "ming", "label": "명궁",
          "branch": { "key": "xu", "label": "술" },
          "stem": { "key": "bing", "label": "병" },
          "isBodyPalace": false,
          "majorStars": [
            { "key": "ziwei", "label": "자미", "brightness": { "key": "de", "label": "득" }, "mutagen": null },
            { "key": "tianxiang", "label": "천상", "brightness": { "key": "de", "label": "득" }, "mutagen": null }
          ],
          "minorStars": [
            { "key": "lingxing", "label": "영성", "brightness": { "key": "miao", "label": "묘" }, "mutagen": null }
          ],
          "decadal": { "from": 5, "to": 14, "isCurrent": false }
        },
        ...
      ],
      "mutagens": [
        { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "quan", "label": "화권", "starKey": "wuqu", "starLabel": "무곡", "palaceKey": "wealth", "palaceLabel": "재백궁" },
        { "type": "ke", "label": "화과", "starKey": "taiyin", "starLabel": "태음", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "ji", "label": "화기", "starKey": "tiantong", "starLabel": "천동", "palaceKey": "health", "palaceLabel": "질액궁" }
      ],
      "currentDecadal": { "palaceKey": "children", "from": 35, "to": 44 },
      "yearly": { "palaceKey": "wealth", "year": 2026 }
    },
    "features": [
      "bright:紫微=得", "co:紫微+天相@命", "cs:命=胎", "dir:逆", "hua:祿=太陽@子女",
      "lhua:忌=廉貞@流年", "limit:大限@子女", "limit:小限@辰", "ming:戌", "mingzhu:祿存",
      "star:天姚@辰", "star:紫微@命", "year:庚", "yy:陽女", ...
    ],
    "notes": { "lateZiNotice": null, "approximateTimeNote": null }
  }
}

{
  "success": false,
  "statusCode": 400,
  "code": "birth_time_required",
  "message": "Zi Wei Dou Shu needs the birth hour (hour 0-23). ...",
  "partial": {
    "birthYearMutagens": [
      { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양" },
      ...
    ],
    "yearStemStars": [
      { "key": "lucun", "label": "녹존", "branch": { "key": "shen", "label": "신" } },
      ...
    ]
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/identity \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male" }'

{
  "success": true,
  "data": {
    "saju": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { ... }
    },
    "sipsin_map": { "year_cheongan": "비견", "year_jiji": "정관", "month_cheongan": "겁재", ... },
    "strength": { "dayMaster": "경", "score": -60, "result": "신약", "level": "중약", ... },
    "rooting_hints": { ... },
    "season_strength_hint": { "season": "여름", "strength_label": "최약(最弱)", ... },
    "sinsal_list": [ { "id": "shinsal_haksang", "name": "학당", "name_hanja": "學堂", "category": "길신", ... } ],
    "gongmang": { "sun": "갑술순", "void_branches": ["신", "유"], "hits": [] },
    "samjae": { "is_in_samjae": false, "current_year_branch": "오" },
    "yongshin": { "method": "조후", "primary": "수", ... },
    "timeline": { "current": { "daeun": { "startAge": 27, "endAge": 37, "stem": "갑", "branch": "신", ... }, ... } },
    "gyeokguk": { "primary": "비견격", ... },
    "mbti_inference": { "e_i": 48, "s_n": -8, "t_f": 16, "j_p": -18, "inferred": "ESFJ", ... },
    ...
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-mbti \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male", "mbti": "INFJ" }'

{
  "success": true,
  "data": {
    "wonkuk": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { "cheongan": "임", "jiji": "오", "ohaeng": "수" }
    },
    "pillarCount": 4,
    "dayMaster": "경",
    "strength": "신약",
    "ohaengCount": { "목": 0, "화": 3, "토": 1, "금": 3, "수": 1 },
    "ohaengState": { "목": "lack", "화": "balanced", "토": "lack", "금": "balanced", "수": "lack" },
    "dominantSipseong": ["관성"],
    "mbti": {
      "type": "INFJ",
      "source": "letters",
      "axes": {
        "E_I": { "value": 25, "letter": "I", "band": "slight" },
        "S_N": { "value": 25, "letter": "N", "band": "slight" },
        "T_F": { "value": 25, "letter": "F", "band": "slight" },
        "J_P": { "value": 75, "letter": "J", "band": "slight" }
      }
    },
    "sajuLean": {
      "E_I": { "lean": "balanced", "weights": { "E": 1, "I": 1 }, "ruleIds": ["R-MBTI-OHAENG-010", "R-MBTI-STRENGTH-002"] },
      "S_N": { "lean": "S", "weights": { "S": 1 }, "ruleIds": ["R-MBTI-OHAENG-006"] },
      "T_F": { "lean": "T", "weights": { "T": 2 }, "ruleIds": ["R-MBTI-STEM-007"] },
      "J_P": { "lean": "J", "weights": { "P": 1, "J": 2 }, "ruleIds": ["R-MBTI-OHAENG-008", "R-MBTI-SIPSEONG-002"] }
    },
    "comparison": [
      { "axis": "E_I", "label": "에너지 방향(E·I)", "user": "I", "userBand": "slight", "saju": "balanced", "relation": "neutral",
        "text": "에너지 방향(E·I): 사주에서는 어느 한쪽으로 기우는 경향이 뚜렷하지 않아요. 입력은 I 쪽이에요." },
      { "axis": "S_N", "label": "인식 방식(S·N)", "user": "N", "userBand": "slight", "saju": "S", "relation": "different",
        "text": "인식 방식(S·N): 사주와 다른 면을 키운 것으로 볼 수 있어요. 사주는 S 쪽 경향이 있고, 입력은 N 쪽이에요." },
      { "axis": "T_F", ... },
      { "axis": "J_P", "label": "생활 방식(J·P)", "user": "J", "userBand": "slight", "saju": "J", "relation": "same",
        "text": "생활 방식(J·P): 사주와 같은 방향이에요. 사주에서 보이는 J 쪽 경향이 입력에도 드러나요." }
    ],
    "matchedRules": [
      { "id": "R-MBTI-STEM-007", "statement": "庚 일간은 단단한 쇠의 기운으로 읽혀, 기준을 세워 따져 보고 결단하는 쪽(T)으로 기울기 쉬운 경향이 있어요." },
      ...
    ],
    "caveats": [ { "id": "R-MBTI-CAVEAT-001", "statement": "사주와 MBTI를 잇는 이 해석은 고전 명리 이론이 아니라 현대의 해석 관행이에요. ..." }, ... ],
    "caveatRuleId": "R-MBTI-CAVEAT-001",
    "interim": false,
    "kbStatus": "literature",
    "kbVersion": "2026.10.16-2",
    "engineVersion": "saju-mbti-1"
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
  "timezone": "Asia/Seoul", "gender": "male",
  "date": "2026-10-10",
  "temperatureC": 16, "weather": "cloudy", "humidity": 60,
  "mbtiBehavior": true
}

{
  "success": true,
  "data": {
    "date": "2026-10-10",
    "summary": {
      "ilju": "경진",
      "day_master": "경",
      "gyeokguk": "비견격",
      "gyeokguk_reason": "월지 사 중기(경) 투간 [연간=경]",
      "inferred_mbti": "ESFJ",
      "today_mbti": "ESFJ",
      "current_mbti": "ESFJ",
      "strength_label": "신약",
      "yongshin": "수",
      "today_date": "2026-10-10",
      "today_ganji": "정사",
      "today_day_ohaeng": "화",
      "today_sipsin": "정관",
      "flow_score": 60,
      "flow_tier": "good",
      "top_favored_task_type": "routine",
      "top_caution_task_type": "movement",
      "active_sinsal_names": ["학당", "암록", "복성귀인", "화개살", "자형(오오)"],
      "in_samjae": false,
      "daily_flow": "오늘(정사일) 화 에너지가 흘러 소통·확장에 유리해."
    },
    "omen": {
      "relation": { "type": "GEUK", "label": "조율의 날" },
      "color": { "name": "주황", "hex": "#FFA45B", "ohaeng": "화" },
      "food": "고추장비빔밥",
      "keyword": "공개",
      "message": "표현하고 싶은 마음과 주변 반응이 엇갈릴 수 있는 날이에요. 즉흥적인 말보다 한 박자 늦춘 표현이 좋아요.",
      "luckyHour": "오전 11시 ~ 오후 1시",
      "avoidHour": "밤 11시 이후",
      "activity": "칭찬 먼저 하기"
    },
    "taskAffinity": [
      { "taskType": "focus", "score": -0.25, "verdict": "neutral",
        "reason": "길 십신 2개 일치 · 흉 십신 2개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" },
      { "taskType": "creative", "score": -0.75, "verdict": "caution", "reason": "..." },
      ...,
      { "taskType": "routine", "score": 0.25, "verdict": "favored",
        "reason": "길 십신 4개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" }
    ],
    "fashion": {
      "temperatureC": 16, "tempBand": "T3",
      "main": "버건디 자켓", "accent": "가죽 벨트",
      "colorAttachLabel": "반지나 메탈 액세서리에",
      "byTime": {
        "morning": { "main": "버건디 자켓", "accent": "가죽 벨트", "tempBand": "T3" },
        "noon": { ... }, "evening": { ... }
      },
      "mood": {
        "feelsLikeC": 16, "tempBand": "jacket", "humidBand": "normal", "weatherKey": "cloudy",
        "morning": { "headline": "흐린 자켓 새벽", "body": "햇볕 없어 살짝 서늘. 자켓 한 벌.", "carry": [] },
        "noon": { ... }, "evening": { ... }
      }
    },
    "mbtiBehavior": {
      "mbti": "ESFJ",
      "headline": "협력·돌봄",
      "actions": ["약속·일정 챙기기 좋은 날", "주변에 도움 줄 수 있는 일 1개", "집·환경 정돈", "내 페이스도 지키기 — 다 떠안지 않기"],
      "closingLine": "주변과 결이 맞아 흐름이 부드러워요."
    }
  }
}

{
  "dream": "바다에서 커다란 물고기를 두 손으로 잡는 꿈을 꿨어요"
}

{
  "success": true,
  "data": {
    "lang": "ko",
    "mode": "glossary",
    "items": [
      { "keywords": ["바다"], "score": 1 },
      { "keywords": ["물고기"], "score": 0.979 },
      { "keywords": ["손"], "score": 0.749 }
    ]
  }
}

"kbMatches": [
  {
    "ruleId": "R-DREAM-DRAGON-002",
    "area": "DRAGON",
    "polarity": "positive",
    "status": "verified",
    "statement": "『주공해몽서』(돈황본 P.3908, 第十二 龍蛇章)는 뱀(虵=蛇)이 길에 있는 꿈(夢見虵當道者)에 대해 「大吉」라고 적는다(글자대로: 크게 길하다).",
    "quote": {
      "text": "夢見虵當道者大吉",
      "sourceId": "SRC-DREAM-P3908",
      "source": "『周公解夢書』 (敦煌 P.3908)",
      "location": "P.3908 第十二 龍蛇章 f09/左/行3下",
      "foundAt": "dream-pd/dunhuang-p3908-bnf/P3908-TRANSCRIPTION-merged.md:198"
    },
    "caveatRuleIds": [],
    "matchedTerms": ["구렁이", "길"]
  }
]

{
  "modelName": "face_landmarker",
  "modelVersion": "float16/[email protected]",
  "normalization": "face-norm-1",
  "landmarks": [[0.5012, 0.3121, -0.031], … 478개 …],
  "imageWidth": 1080,
  "imageHeight": 1350,
  "hairline": [0.501, 0.182],
  "quality": { "yawDeg": 2.1, "pitchDeg": -3.4, "blendshapes": { "eyeBlinkLeft": 0.05, "jawOpen": 0.02 } }
}

{
  "success": true,
  "data": {
    "normalization": "face-norm-1",
    "keys": { "face.thirds.upper_ratio": 0.3333, "face.brow.length_vs_eye": 1.625, "face.brow.outer_overhang": 0.1648, … },
    "reasons": {},
    "quality": { "rollDeg": 0, "iodPx": 158, "flags": [] },
    "kbMatches": [
      {
        "ruleId": "R-FACE-PALACE-031",
        "area": "PALACE",
        "kind": "interpretation",
        "polarity": "positive",
        "status": "verified",
        "statement": "『古今圖書集成』 相術部彙考 「十二宮訣」 兄弟는 눈썹이 눈보다 길게 지나가면(眉長過目) …라고 적는다 …",
        "quote": { "text": "眉長過目，三四兄弟", "sourceId": "SRC-FACE-HUIKAO", "source": "…", "location": "…", "foundAt": "…" },
        "caveatRuleIds": ["R-FACE-CAVEAT-001"],
        "matchedConditions": [{ "key": "face.brow.outer_overhang", "op": "gt", "value": 0, "actual": 0.1648 }]
      }
    ]
  }
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "lang": "ko",
  "endUserId": "member-1024"
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "creases": [
    { "line": "life", "points": [[0.42, 0.38], [0.36, 0.52], [0.34, 0.71]] },
    { "line": "heart", "points": [[0.78, 0.33], [0.6, 0.31], [0.47, 0.34]] }
  ]
}

"processing": {
  "provider": "OpenAI",
  "model": "gpt-5.6-luna",
  "region": "US",
  "store": false,
  "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제",
  "imageStored": false
}

{
  "success": true,
  "data": {
    "items": [
      {
        "key": "forehead",
        "label": "이마",
        "observation": "이마가 넓고 둥글게 보여요.",
        "reason": "넓은 이마는 생각을 넓게 펼치는 쪽으로 읽혀요. 떠오른 계획을 글로 정리해 두면 장점이 더 살아나요."
      },
      {
        "key": "eyes",
        "label": "눈",
        "observation": "눈매가 길고 가로로 뻗어 있어요.",
        "reason": "긴 눈매는 사람과 상황을 찬찬히 살피는 쪽으로 읽혀요."
      }
    ],
    "summary": "생각을 넓게 펼치고 찬찬히 살피는 인상으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "image",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": []
    }
  }
}

{
  "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"], "strokes": [null, 5, 7], "meanings": ["쇠", null, null] },
  "birth": { "year": 1990, "month": 5, "day": 17, "hour": 9 },
  "consent": { "version": "name-consent-2026-10", "subject": "end_user" }
}

{
  "success": true,
  "data": {
    "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"] },
    "deterministic": {
      "surnameLength": 1,
      "syllables": [
        { "index": 0, "hangul": "김", "hanja": "金", "strokes": 8, "strokeSource": "kb", "strokeNote": null, "strokeRuleId": "R-NAME-STROKE-004", "soundElement": "wood", "soundRuleId": "R-NAME-SOUND-004", "meaning": "쇠", "rootElement": "metal" },
        { "index": 1, "hangul": "민", "hanja": "民", "strokes": 5, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "water", "soundRuleId": "R-NAME-SOUND-010", "meaning": null, "rootElement": null },
        { "index": 2, "hangul": "수", "hanja": "秀", "strokes": 7, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "metal", "soundRuleId": "R-NAME-SOUND-006", "meaning": null, "rootElement": null }
      ],
      "soundFlow": { "elements": ["wood", "water", "metal"], "relations": ["reverse_generating", "reverse_generating"], "generating": 0, "overcoming": 0, "score": 0.5 },
      "suri": {
        "won": { "sum": 12, "number": 12, "grade": "bad" },
        "hyung": { "sum": 13, "number": 13, "grade": "good" },
        "i": { "sum": 15, "number": 15, "grade": "good" },
        "jeong": { "sum": 20, "number": 20, "grade": "bad" }
      },
      "suriMissing": null,
      "yongshin": { "element": "wood", "supplied": true, "suppliedBy": ["sound"] },
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    },
    "interpretation": { "text": "첫 글자는 목, 가운데 글자는 수, 끝 글자는 금 기운이에요. 소리가 서로 부딪치지 않고 이어지는 이름으로 읽혀요." },
    "items": [
      { "key": "sound_flow", "label": "발음오행 흐름", "score": 0.5, "reason": "김(목(木)) → 민(수(水)) → 수(금(金)) · 상생 0 · 상극 0", "ruleId": "R-NAME-SOUND-011" },
      { "key": "suri_hyung", "label": "형격", "grade": "good", "score": 13, "reason": "획수 합 13 → 13수(길)", "ruleId": "R-NAME-MODERN-001" },
      { "key": "yongshin_match", "label": "용신 보완", "grade": "supplied", "reason": "용신 목(木)을 이름이 발음으로 채워 줘요" }
    ],
    "summary": "부드럽게 이어지는 소리에 용신 기운이 담긴 이름으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "name",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    }
  }
}

塔羅 API

POST /api/v1/partners/v1/tarot

指定張數（count，1~10 張）或牌陣（spread）後，會從 78 張牌組（大阿爾克那 22 張 · 小阿爾克那 56 張）中不重複地抽牌，並為每張牌回傳正位·逆位、關鍵字、牌義、牌卡圖片網址。沒有 AI 解讀 — 牌義就是該牌固定的文字。因此使用方式有三種。

• 只呼叫塔羅來做應用程式 — 將回應中的牌名·牌義·圖片直接繪製在畫面上。
• 塔羅 + LLM 解讀 — 將抽出的牌傳入 LLM API，自行撰寫解讀。
• 與八字 AI 組合 — 在 AI 八字解讀請求中加入 tarot，就會連同八字解讀一起解讀塔羅（包含項目）。

請求參數

請求範例

{
  "spread": "past-present-future",
  "question": "올해 하반기에 이직해도 될까요?",
  "seed": "user-1042:2026-10-10"
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/tarot \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "lang": "en", "reversed": false}'

回應範例（節錄 1 張牌）

{
  "success": true,
  "data": {
    "lang": "ko",
    "count": 3,
    "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
    "reversedAllowed": true,
    "seed": "hrum-example-1",
    "cards": [
      {
        "position": 1,
        "positionLabel": "과거",
        "id": "wands_10",
        "name": "완드의 10",
        "nameEn": "Ten of Wands",
        "arcana": "wands",
        "reversed": true,
        "keywords": ["내려놓기", "위임", "해방"],
        "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.",
        "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp"
      }
    ],
    "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp",
    "question": "올해 하반기에 이직해도 될까요?",
    "costPoints": 20
  }
}

• cards[]：position（從 1 開始，抽牌順序 = 牌陣位置）· positionLabel（牌陣位置名稱，以 count 抽牌時為 null）· id（與語言無關的牌卡唯一值）· name（請求的語言）· nameEn · arcana（major | wands | cups | swords | pentacles）· reversed · keywords·meaning（抽出方向的內容）· imageUrl。
• spread：以 count 抽牌時為 null。
• 牌卡圖片：imageUrl·cardBackUrl 為 WebP（寬 600px），網址中含有版本（v2），因此不會變動 — 可以下載後快取並直接使用。逆位的牌請將圖片旋轉 180 度顯示（圖片本身只有正位一張）。
• 圖片來源：1909 年 Rider-Waite（Pamela Colman Smith，公共領域）原版掃描。78 張牌與牌背皆為 Wikimedia Commons 上的 1909 年原版掃描，各檔案的來源·授權請見來源清冊。舊網址（v1）也會回傳相同的圖片，因此不需要更改已儲存的網址。
• costPoints：本次呼叫的扣款金額（₩）。

價格

• 每次呼叫固定價格 — 抽 1 張或 10 張都一樣。價格請見價格中的計算型表格。僅成功的呼叫計費，相同輸入的重複呼叫也會各自計費（冪等性）。
• 輸入錯誤（400）、餘額不足（402）不計費。用量紀錄的 endpoint 為 tarot。
• 在尚未開放的狀態下呼叫時回傳 404 tarot_not_enabled（不計費）。

Waite 原典依據 kb

開放後回應會附上 kb。針對每張抽出的牌，從 A. E. Waite《The Pictorial Key to the Tarot》（1910 年，公共領域）原文中，以規則 ID（R-TAROT-*）與原文引用回傳該牌的正位·逆位牌義。上方的 meaning·keywords 維持不變，只會多加 kb，價格相同。

• kb.cards[]：position · id · reversed · drawn（抽出方向的牌義）· upright · reversedMeaning · positionRule。每個牌義含 ruleId · status · statement（韓文）· quotes[]（quote 英文原文、location 章節、foundAt 原文行）· variants[]（Waite 記載的其他說明 alternative、第三部 §4 的附加意義 additional）。
• status 直接沿用 KB 的標示（verified = 有原文引用）。Waite 未記載牌義的位置（聖杯二逆位）為 ruleId: null、status: "disputed"。
• method: "celtic-cross"：Waite 在書中記載的凱爾特式占卜法（10 張）。用來取代 count·spread 傳送，10 個位置各自的 Waite 位置意義會放在 positionRule。其他 spread 是 Waite 原文中沒有的排列，因此沒有位置依據（kb.method: null）。
• kb.caveats：Waite 所說牌義會隨位置改變的說明，以及使用原則（是占卜的工具，不能取代健康·法律·財務方面的決定）。
• 開放前傳送 method 時回傳 404 tarot_kb_not_enabled（不計費）。

{
  "method": "celtic-cross",
  "seed": "user-1042:2026-10-11"
}

錯誤代碼

除了通用錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

count·spread·method 必須正好傳送其中一個。傳送兩個以上或都沒傳時回傳通用 400。

本命盤 API（西洋占星） 停止販售

POST /api/v1/partners/v1/natal-chart

以出生年月日時計算西洋占星的本命盤（太陽·月亮·水星·金星·火星·木星·土星 7 顆天體位置 + 上升星座）。不包含天王星·海王星·冥王星。以西洋占星的回歸黃道為準，而非節氣。

請求參數

回應欄位

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/natal-chart \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-05-15",
    "birthTime": "12:00",
    "birthLatitude": 37.5665,
    "birthLongitude": 126.978,
    "birthTimezoneOffset": 540,
    "birthTimePrecision": "exact"
  }'

回應範例

{
  "success": true,
  "data": {
    "sun": {
      "body": "Sun",
      "sign": "황소자리",
      "signEn": "Taurus",
      "element": "흙",
      "degreeInSign": 24.03,
      "eclipticLongitude": 54.0343
    },
    "moon": { "body": "Moon", "sign": "염소자리", "signEn": "Capricorn", "element": "흙", ... },
    "mercury": { "body": "Mercury", "sign": "황소자리", "signEn": "Taurus", ... },
    "venus": { "body": "Venus", "sign": "양자리", "signEn": "Aries", "element": "불", ... },
    "mars": { ... },
    "jupiter": { ... },
    "saturn": { ... },
    "ascendant": {
      "body": "Ascendant",
      "sign": "사자자리",
      "signEn": "Leo",
      "element": "불",
      "degreeInSign": 23.13,
      "eclipticLongitude": 143.1256
    },
    "coordsBasis": "coords",
    "engineVersion": "natal-2"
  }
}

上述範例請求：{"birthDate": "1990-05-15", "birthTime": "12:00", "birthLatitude": 37.5665, "birthLongitude": 126.978, "birthTimezoneOffset": 540, "birthTimePrecision": "exact"}（實際引擎輸出節錄）。

{
  "success": true,
  "data": {
    "sun": { ... }, "moon": { ... }, ...,
    "readings": {
      "dignities": [
        { "key": "Me_dom", "lang": "ko",
          "text": "수성이 본궁인 쌍둥이자리나 처녀자리에 있으면 정보를 모으고 분류해 말로 옮기는 기능이 막힘없이 또렷하게 드러나요. 생각이 많아질 때 하나를 골라 끝까지 파고들면 그 명료함이 실제 성과로 이어져요." },
        { "key": "Sa_dom", "lang": "ko",
          "text": "토성이 본궁인 염소자리나 물병자리에 있으면 책임을 지고 구조를 세워 반복 훈련으로 숙련을 쌓는 기능이 막힘없이 또렷하게 드러나요. 기준이 지나치게 굳어질 때 쉬어 갈 틈을 일정에 남겨 두면 그 인내가 성숙하게 쓰여요." }
      ],
      "aspects": [
        { "key": "Me_Sa_tr", "deviation": 0.04, "lang": "ko",
          "text": "수성과 토성의 트라인은 절제와 의지를 생각에 더해, 서두르지 않고 앞을 내다보며 구조를 짜는 데 힘이 실려요. 변화가 필요한 순간에 익숙한 방식만 고집할 수 있으니 새 방법도 한 번 시험해 보세요." },
        { "key": "Mo_Ma_sq", "deviation": 1.03, "lang": "ko",
          "text": "달과 화성이 스퀘어를 이루면 감정이 올라오는 순간 욱하거나 규칙에 반발하는 쪽으로 기울 수 있어요. 화가 난 뒤 반응을 한 템포 늦추는 연습을 하면 그 뜨거움이 지켜야 할 것을 지키는 힘으로 바뀌어요." }
      ],
      "lang": "ko",
      "costWon": 20
    }
  }
}

注意事項

• 價格：₩20 / 次呼叫（依量計費） · readings: true 時另加 ₩20（合計 ₩40）
• 日期驗證：錯誤的日期（例：2 月 30 日）或錯誤的座標/時區會回傳 400 錯誤，且不計費。
• 上升星座計算：需要出生時刻 + birthTimePrecision（exact/approximate，省略則為 exact）+ 緯度/經度全部齊備。缺少任何一項時 ascendant 為 null。
• 解讀段落錯誤：readings: true 但帳號未開通時回傳 404 natal_readings_not_enabled，無法載入段落時回傳 503 natal_readings_unavailable — 兩者皆不計費。
• 太陽/月亮/上升星座：所有行星與軸點皆以回歸黃道（西洋占星標準）為準。
• 2026-10-17 變更（engineVersion natal-2）：傳送 birthTime 而省略 birthTimePrecision 時，現在會以該時刻計算（以前會忽略時刻而以正午計算，上升星座為 null）。與其他 endpoint 的規則相同。沒有 birthTime 或直接傳送精確度的呼叫，結果維持不變。

錯誤代碼

除了通用錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

占星全覽 API

如同萬年曆，一次呼叫即回傳全部占星計算。預設為完整本命盤（太陽~冥王星 10 顆天體 · 月交點 · 4 個軸點 · 宮位（預設 Placidus）· 相位 · 品位），在請求中加上區塊時，行運 + 次限推運（timing）與雙人合盤比較（partner）也會一併放在同一個回應中。只取用需要的部分即可。不使用 LLM。除了數值與規則鍵（features）之外，HRUM 預先寫好的解讀段落（readings）一律附上，不另收費。與 INTA 使用相同的共用占星引擎，天體位置已與 NASA/JPL Horizons·Swiss Ephemeris 的基準值比對驗證（行星誤差 0.005° 以內）。解讀參數（容許度·相位種類·品位表）全部來自古典原典的規則，原典之間有分歧的值（行運·推運容許度）不設預設值，由您自行選擇（見下方「預設值與必須自行選擇的值」）。

POST /api/v1/partners/v1/astrology

出生輸入與本命盤 API相同（birthDate · birthTime · birthTimePrecision · birthLatitude · birthLongitude · birthTimezoneOffset，預設 540 = KST，自動反映韓國夏令時間·1954~61 年 UTC+8:30）。省略 birthTimePrecision 時為 unknown（以正午為準）。

timing 區塊內容：

請求範例 1 — 預設（僅本命盤）

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["placidus", "whole_sign"]
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "birthLatitude": 37.5665, "birthLongitude": 126.978, "minorAspects": true, "lang": "en"}'

回應範例 1（節錄，實際引擎輸出）

{
  "success": true,
  "data": {
    "natal": {
      "utc": "1990-05-15T05:30:00.000Z",
      "timePrecision": "exact",
      "timeKnown": true,
      "zodiac": "tropical",
      "lang": "ko",
      "bodies": [
        { "id": "Sun", "longitude": 54.1347, "sign": "Taurus", "signKey": "tau", "signName": "황소자리", "degreeInSign": 24.1347, "speed": 0.9643, "retrograde": false, "dignities": [], "house": { "placidus": 9, "whole_sign": 9 } },
        { "id": "Moon", "longitude": 293.8244, "sign": "Capricorn", "signKey": "cap", "signName": "염소자리", "degreeInSign": 23.8244, "speed": 12.2943, "retrograde": false, "dignities": ["det"], "house": { "placidus": 4, "whole_sign": 5 } },
        ...
      ],
      "nodes": [
        { "id": "MeanNode", "longitude": 311.3535, "sign": "Aquarius", "signName": "물병자리", "speed": -0.0529,
          "south": { "longitude": 131.3535, "sign": "Leo", "signName": "사자자리", ... } },
        { "id": "TrueNode", ... }
      ],
      "angles": { "asc": 173.5996, "mc": 82.8067, "dsc": 353.5996, "ic": 262.8067,
        "ascSign": { "sign": "Virgo", "signName": "처녀자리", ... }, "mcSign": { ... }, "dscSign": { ... }, "icSign": { ... }, "polar": false },
      "anglesOmitted": null,
      "houseSystems": ["placidus", "whole_sign"],
      "houses": {
        "placidus": { "cusps": [173.5996, 199.6989, 229.8749, ...], "bodies": { "Sun": 9, "Moon": 4, "Jupiter": 10, ... } },
        "whole_sign": { "cusps": [150, 180, 210, ...], "bodies": { "Sun": 9, "Moon": 5, ... } }
      },
      "housesExcluded": [],
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Jupiter", "b": "Uranus", "type": "opposition", "code": "op", "key": "Ju_Ur_op", "separation": 179.6986, "orb": 0.3014, "orbLimit": 8, "strength": "exact", "applying": false, "outOfSign": false },
        { "a": "Sun", "b": "Moon", "type": "trine", "code": "tr", "key": "Su_Mo_tr", "orb": 0.3104, "orbLimit": 8, "strength": "exact", "applying": true, "outOfSign": false },
        ...
      ],
      "dignities": { "Sun": [], "Moon": ["det"], "Mercury": [], "Venus": ["det"], "Mars": [], "Jupiter": ["exa"], "Saturn": ["dom"] },
      "moonSignUncertain": false,
      "features": [
        { "type": "planet_sign", "key": "Su_tau" },
        { "type": "dignity", "key": "Mo_det" },
        { "type": "planet_retrograde", "key": "Me_rx" },
        { "type": "planet_house", "key": "Su_h9", "system": "placidus" },
        { "type": "aspect", "key": "Su_Mo_tr", "strength": "exact", "applying": true, "orb": 0.31 },
        { "type": "meta", "key": "time_known" },
        ...
      ]
    },
    "readings": {
      "dignities": [
        { "key": "Mo_det", "text": "달이 염소자리에서 손상 자리에 있으면 감정을 바로 내보이기보다 책임과 일의 질서 속에서 조심스럽게 다루는 경향이 있어요. ...", "lang": "ko" },
        { "key": "Ve_det", ... }, { "key": "Ju_exa", ... }, { "key": "Sa_dom", ... }
      ],
      "aspects": [
        { "key": "Su_Mo_tr", "text": "태양과 달의 트라인은 의지와 정서가 같은 곳을 바라봐, 스스로 길을 내며 생활 전반을 고르게 꾸려 가는 힘이 실려요. ...", "lang": "ko", "deviation": 0.31 },
        { "key": "Su_Sa_tr", ... }, { "key": "Mo_Sa_cj", ... }, ...
      ],
      "lang": "ko"
    },
    "readingsUnavailable": false,
    "costPoints": 50
  }
}

沒有傳送 timing·partner 時，回應中完全沒有 timing·synastry 鍵。

• bodies[]：太陽·月亮·水星·金星·火星·木星·土星·天王星·海王星·冥王星。longitude 為黃經（0° = 春分點，回歸黃道），speed 為度/日 — 負數表示 retrograde: true。每顆天體都直接附上 signName（lang 語言的星座名稱）· degreeInSign（星座內度數 0~30°）· house（依請求的宮制分別列出宮位編號，與 houses[system].bodies 相同的值 — 未計算宮位時為 {}），光靠這些就能繪製星盤表格。
• dignities：太陽~土星的品位（dom 本垣 · exa 擢升 · det 失勢 · fal 落陷，列出所有符合的狀態）。與 bodies[].dignities 為相同的值。
• nodes[]：MeanNode（平均交點）· TrueNode（真實交點）= 北交點，south = 南交點（+180°）。
• angles：ASC·MC·DSC·IC。僅在出生時刻（exact/approximate）與座標兩者皆有時計算。否則為 null，並由 anglesOmitted 告知原因（time_unknown | coordinates_missing）。此時也不計算宮位，houses 為 {}。
• houses：依請求的宮制分別列出 cusps（第 1~12 宮起始黃經）+ bodies（各天體的宮位編號）。
• houseSystems·houses：實際計算的宮制。出生地位於極圈內（angles.polar = 緯度約 66.56° 以上）時，Placidus 可能無法定義，因此改以 Porphyry 計算，並以 houses.porphyry.fallbackFrom = "placidus" 標示（不會暗中替換）。判定依出生地緯度，因此同一出生地不論時刻都會得到相同的宮制。housesExcluded 是其他無法計算的宮制及其原因（並非錯誤回應）。
• aspects[]：orb = 偏離正相位的度數，strength = exact（2° 以內）· close（上限的一半以內）· wide，applying = 正在接近正相位時為 true（不明則為 null），outOfSign = 跨越星座邊界的相位（解讀時減弱一級）。
• moonSignUncertain：時刻不詳且當天內月亮星座改變時為 true — 此時 features 中月亮的 planet_sign 會附上 "uncertain": true。
• readings（一律包含，不另收費）：HRUM 預先寫好的解讀段落。dignities[] = 品位（太陽~土星，每顆天體取最強的一個狀態），aspects[] = 本命天體之間的相位，依容許度由小到大排列。每個段落含 key（與 features·aspects[].key 相同的鍵）· text · lang（段落實際語言 — 沒有請求語言的段落時為 ko）· deviation（僅相位，偏離正相位的度數）。只有已預先寫好段落的鍵才會附上，其餘略過（不會即時編寫）— 涉及天王星·海王星·冥王星的相位與次要相位沒有段落，因此不包含。沒有出生時刻時，涉及月亮的相位不附上；月亮星座不確定時，月亮品位不附上。上方範例（1990-05-15 14:30 首爾）為 16 個相位中的 7 個 + 品位 4 個 = 11 個段落。
• readingsUnavailable：無法載入解讀段落時為 true — 此時星盤計算結果仍照常回傳，readings 為空陣列，價格（₩50）也不變。
• features[]：用於比對規則資料庫的鍵。planet_sign Su_ari · planet_retrograde Me_rx · dignity Ma_dom · node_sign MNn_leo·TNn_leo·Nn_leo·Sn_aqu（Nn·Sn 為 node 選項所選的交點）· angle_sign Asc_sco · planet_house Ve_h7（+system）· aspect Su_Mo_cj（交點只算合相 3° — Mo_Nn_cj·Sa_Sn_cj·Nn_Asc_cj，與上升點的組合僅在有出生時刻時）· house_cusp_sign h12_ari（第 12 宮宮首在牡羊座）· house_empty h6（10 顆行星都不在的宮位）· house_ruler_house h1_h7（第 1 宮宮主星在第 7 宮）· house_ruler_sign h7_lib（第 7 宮宮主星在天秤座）— 宮主星為宮首星座的傳統守護星（太陽~土星 7 顆行星）· planet_rising Ju（第 1 宮，或在第 12 宮且距上升點 6° 以內）— 這五類會附上 +system，僅在有出生時刻與座標時出現 · planet_solar Ve_cazimi（距太陽 17′ 以內）/ Me_combust（17′~8°30′，與太陽同星座）/ Ma_beams（其餘 17° 以內）— 三個階段不重疊 · moon_phase waxing·waning · meta time_known（有時刻 — exact·approximate）/ time_hour_level（approximate 時追加）/ time_unknown。相位類鍵（aspect·transit·progressed·syn_aspect）會附上 orb（偏離正相位的度數，小數點後兩位），且僅在相位跨越星座邊界時附上 "outOfSign": true — 這是用來對應規則鍵屬性 [orb=…]·[outOfSign=true] 的值。出生時刻不詳時，涉及月亮的本命相位會附上 "uncertain": true。天體縮寫 Su Mo Me Ve Ma Ju Sa Ur Ne Pl，交點 MNn TNn Nn Sn，相位代碼 cj（0°）sx（60°）sq（90°）tr（120°）op（180°）· 次要 ssx（30°）ssq（45°）sqq（135°）qcx（150°）。

請求範例 2 — 含 timing（行運 + 次限推運）

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "timing": { "at": "2026-10-11T09:00:00+09:00", "orbDegrees": 3, "yearLength": "tropical" }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "timing": {"orbDegrees": 2, "progressions": false}}'

回應範例 2（節錄，natal 與範例 1 形式相同）

{
  "success": true,
  "data": {
    "natal": { ... },
    "timing": {
      "at": "2026-10-11T00:00:00.000Z",
      "orbDegrees": 3,
      "natalPoints": ["Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Asc", "MC"],
      "transits": {
        "bodies": [ { "id": "Sun", "longitude": 197.6966, "sign": "Libra", "signName": "천칭자리", "speed": 0.9889, "retrograde": false, ... }, ... ],
        "aspects": [
          { "a": "Mars", "b": "Mercury", "type": "square", "key": "tMa_nMe_sq", "orb": 0.6358, "orbLimit": 3, "strength": "exact", "applying": true, "outOfSign": false },
          ...
        ]
      },
      "progressions": {
        "yearLength": "tropical",
        "yearLengthDays": 365.24219,
        "ageYears": 36.4081,
        "instant": "1990-06-20T15:17:39.048Z",
        "bodies": [ { "id": "Sun", "longitude": 89.0352, "sign": "Gemini", "signName": "쌍둥이자리", ... }, ... ],
        "aspects": [
          { "a": "Uranus", "b": "Mercury", "type": "trine", "key": "pUr_nMe_tr", "orb": 0.0862, "orbLimit": 3, "strength": "exact", "applying": false, "outOfSign": false },
          ...
        ]
      },
      "features": [
        { "type": "transit", "key": "tMa_nMe_sq", "strength": "exact", "applying": true, "orb": 0.64 },
        { "type": "progressed", "key": "pUr_nMe_tr", "strength": "exact", "applying": false, "orb": 0.09 },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• 行運對象（natalPoints）：本命天體 10 顆 + 有出生時刻·座標時的上升點（Asc）·天頂（MC）。鍵使用 t（行運）·n（本命）前綴 — tSa_nSu_cj = 行運土星與本命太陽合相。
• transit_house tSa_h7（行運土星在本命第 7 宮）· progressed_house pMo_h4（推運月亮在本命第 4 宮）：各 10 顆行星。本命宮位使用預設宮制（Placidus，極圈內則為 Porphyry + "fallbackFrom": "placidus"），鍵會附上 "system" — 即使傳送不同的 houseSystems，這兩種鍵仍以預設宮制為準。沒有出生時刻或座標時不會出現。
• 推運→本命相位只以本命行星為對象。鍵 pSu_nJu_tr = 推運太陽與本命木星三分相。instant 是作為推運盤所用天空的時刻（出生 + ageYears 日）。
• progressions: false 時 timing.progressions 為 null。省略 yearLength 時為 tropical（365.24219 日）。
• 在 progressions 開啟的狀態下，timing.at 早於出生時刻時回傳 400 at_before_birth（不計費）。
• 時刻不詳時，本命盤以正午為準。以本命月亮為對象的鍵（…_nMo_…）與推運月亮鍵（pMo_…）會附上 "uncertain": true（推運月亮直接承接本命月亮的位置，因此會隨正午假設而有所偏差）。

請求範例 3 — 含 partner（合盤比較）

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "partner": { "birthDate": "1992-11-03", "birthTime": "08:10", "birthTimePrecision": "exact", "birthLatitude": 35.1796, "birthLongitude": 129.0756 }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "partner": {"birthDate": "1992-11-03"}}'

回應範例 3（節錄，natal 與範例 1 形式相同）

{
  "success": true,
  "data": {
    "natal": { ... },
    "synastry": {
      "partner": {
        "utc": "1992-11-02T23:10:00.000Z",
        "timePrecision": "exact",
        "timeKnown": true,
        "moonSignUncertain": false,
        "bodies": [ { "id": "Sun", "longitude": 220.7903, "sign": "Scorpio", "signName": "전갈자리", "speed": 1.0016, "retrograde": false, "dignities": [], ... }, ... ],
        "angles": { "asc": 252.31, "mc": 175.86, "ascSign": { "sign": "Sagittarius", "signName": "사수자리", ... }, "mcSign": { "sign": "Virgo", "signName": "처녀자리", ... } },
        "anglesOmitted": null
      },
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Moon", "b": "Mars", "type": "opposition", "code": "op", "key": "aMo_bMa_op", "orb": 0.2993, "orbLimit": 10, "strength": "exact", "applying": null, "outOfSign": false },
        { "a": "Neptune", "b": "Uranus", "type": "conjunction", "code": "cj", "key": "aNe_bUr_cj", "orb": 0.3898, "orbLimit": 8, "strength": "exact", "applying": null, "outOfSign": false },
        ...
      ],
      "features": [
        { "type": "syn_aspect", "key": "aMo_bMa_op", "strength": "exact", "orb": 0.3 },
        { "type": "syn_aspect", "key": "aNe_bUr_cj", "strength": "exact", "orb": 0.39 },
        { "type": "astro_syn", "key": "Su_Mo_se" },
        { "type": "syn_sign", "key": "aAsc_bAsc_es" },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• 鍵前綴 a = 發出請求的本人，b = partner。aVe_bMa_cj = 本人金星與對方火星合相。檢視本人 10 顆天體（+上升點·天頂）× 對方 10 顆天體（+上升點·天頂）的所有組合（有方向性，因此 aSu_bMo 與 aMo_bSu 是不同的鍵）。
• 上升點（Asc）·天頂（MC）僅在該人的出生時刻與座標兩者皆有時計算（與本人相同的規則，對方見 synastry.partner.angles/anglesOmitted）。涉及軸點的交叉相位只看合相·對分相，容許度 6°。唯有上升點之間的合相（aAsc_bAsc_cj）放寬到 17°（托勒密《四書》— 兩人的上升點在 17° 以內則連結強烈，規則 [orb=17]）。實際相距的度數放在 orb。軸點只要擁有該軸點者的時刻確定即可計算。下降點·天底是上升點·天頂的正對面，因此不另設鍵。
• astro_syn：古典 6 組（太陽–月亮、金星–火星、月亮–金星、太陽–金星、月亮–火星、金星–土星）的星座關係中最強的 2 個。兩個方向合併為一個鍵（Su_Mo_se = 一方的太陽與另一方的月亮為同元素）。syn_sign：本人所有點 × 對方所有點的星座關係（aAsc_bAsc_ss）。兩人的出生時刻都是 exact 時，幸運點（PoF，日夜公式反轉）也納入點中（aPoF_bPoF_ss）— 幸運點與上升點一起約每 4 分鐘移動 1°，因此以時辰為單位（approximate）或時刻不詳時不產生。關係代碼 ss（同星座）· op（對宮星座）· se（同元素）· es（元素相助）· sm（同模式）· ef（元素摩擦）· nt（無關）。
• 容許度表與是否納入次要相位，使用與本命盤相同的 orbs·minorAspects。由於是兩張本命盤之間的比較，沒有入相·出相之分，因此 applying 一律為 null。
• 只要任一方的出生時刻不詳，該人的星盤就以正午為準。涉及該人月亮的相位會在 features 附上 "uncertain": true（月亮一天約移動 13°，變動範圍大於容許度）。與對方軸點配對的相位（aAsc_bMo_…，反方向 aMo_bAsc_…）也相同。
• 不計算對方的宮位（不提供合盤宮位疊加）。

預設值與必須自行選擇的值

• 宮制（預設 placidus）：1819 年·1929 年辭典記載為「通用」的宮制。出生地位於極圈內時以 Porphyry 替代，並以 fallbackFrom 標示。需要其他宮制時請以 houseSystems 選擇。
• 推運一年的長度（預設 tropical 365.24219 日）：原典所說「生日→下一個生日」的一年。與儒略年（julian）的差異，在 80 歲時約為推運時刻 2.5 分鐘。
• 行運·推運容許度（timing.orbDegrees，傳送 timing 時為必填）：各原典不一（正相位前 8° 至 10° 的區間）。留空時回傳 400。
• 涉及冥王星·交點·軸點的本命相位不在預設容許度表中：這些是 Leo（1928）·Heindel（1919）容許度表未涵蓋的點（冥王星於 1930 年發現）。因此本命 aspects 中不會出現這些點（位置·宮位中會出現）。只有合盤比較中的軸點交叉相位以合相·對分相 6°（僅上升點之間的合相為 17°）檢視。

不提供的項目

• 次要品位（三分性 triplicity·界 term·外觀 face）、互容（reception）、本命幸運點（僅用於合盤比較的 syn_sign）、天王星·海王星·冥王星的品位、平行相位·中點
• 推運軸點（推運 ASC·MC）— 原典未訂定方法
• DSC·IC 提供數值，但不產生 features 鍵（南交點以 Sn 鍵產生）
• 新月·滿月·上弦·下弦的月相鍵（moon_phase 只有 waxing·waning）、相對太陽的東方·西方（oriental·occidental）、推運軸點鍵
• 合盤宮位疊加

價格

• 與萬年曆相同，每次 ₩50 — 即使加上 timing·partner 區塊，不論宮制·是否納入次要相位，都是同樣一次 ₩50。回應的 costPoints 為本次扣款金額（₩）。用量紀錄的 endpoint 為 astrology。
• 僅在計算成功時扣款。輸入錯誤（400）、餘額不足（402）不計費。
• 在尚未開放的狀態下呼叫時回傳 404 astrology_not_enabled（不計費）。

錯誤代碼

除了通用錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

運勢走勢 API

以一個人的八字計算大運·流年·流月疊加在命盤（原局）上的走勢，並以供圖表使用的數值與關係清單回傳。一次一人，不使用 LLM。縱軸的值是「疊加運勢干支後的日干側分數」— 在命盤強弱總分上，加上每個運勢干支依與命盤相同的逐字計分表（生扶·剋洩·藏干·通根）所評的分數，並截斷在 ±100 的值，並不衡量運勢的好壞（R-SAJU-UN-034）。身強·中和·身弱的名稱沿用命盤本身的判定，不會因運勢而重新標示。

價格：每次 ₩50（與萬年曆相同，擴大範圍或加上流月也是相同價格）。400 等失敗回應不計費。

所有數值皆由與 INTA 相同的共用八字引擎產生。出生時刻以韓國標準時的歷史時鐘時間（1954~61 年 UTC+8:30，自動反映夏令時間）讀取並與交節時刻比較，因此不論伺服器時區為何，結果都相同。

出生地（2026-10-15 新增，saju-flow-5）：接受與萬年曆 API相同的欄位（birthLatitude·birthLongitude·country·birthTimePrecision），並以相同方式進行真太陽時校正。出生時刻接近時柱·日柱·交節的邊界時，校正會改變命盤的干支，因此請將傳給萬年曆的位置原樣也傳給運勢走勢，兩邊的結果才會使用同一個命盤。不傳送位置時，以與不帶位置呼叫萬年曆時相同的預設處理（目前為不校正）計算，並在回應的 assumedLocation 告知該預設值。

POST /api/v1/partners/v1/saju-flow

請求範例

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "calendar": "solar",
  "gender": "male",
  "timezone": "Asia/Seoul",
  "range": { "fromYear": 1990, "toYear": 2090 },
  "monthsOfYear": 2026
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-flow \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: chart-123:flow:2026" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "calendar": "solar", "gender": "male", "timezone": "Asia/Seoul", "range": {"fromYear": 1990, "toYear": 2090}, "monthsOfYear": 2026}'

回應範例（節錄，實際引擎輸出）

{
  "success": true,
  "data": {
    "engineVersion": "saju-flow-6",
    "kbVersion": "2026.10.11-7",
    "hourKnown": true,
    "natalAmbiguous": null,
    "natal": {
      "score": -37, "result": "중화", "level": "약약",
      "breakdown": { "season": -30, "support": 36, "control": -28, "hidden": -5, "root": 5 },
      "primaryYongshin": "토",
      "shin": { "yongshin": "토", "huishin": "화", "gishin": "목", "gushin": "수", "hanshin": "금" },
      "ruleIds": ["R-SAJU-STR-001", "R-SAJU-STR-018", "R-SAJU-STR-019", "R-SAJU-YONG-170"]
    },
    "daeun": [
      { "startYear": 1997, "endYear": 2006, "startAge": 7,
        "chars": [
          { "pos": "stem", "char": "임", "hanja": "壬", "ohaeng": "수", "sipsin": "식신", "shinRole": "gushin",
            "share": { "support": 0, "control": -8, "hidden": 0, "root": 0, "total": -8 } },
          { "pos": "branch", "char": "오", "hanja": "午", "ohaeng": "화", "sipsin": "정관", "shinRole": "huishin",
            "share": { "support": 0, "control": -10, "hidden": -5, "root": 0, "total": -15 } }
        ],
        "delta": -23, "line": { "value": -60, "clamped": false },
        "relations": [
          { "type": "자형", "from": "daeun", "with": "yearBranch", "a": "오", "b": "오", "ruleId": "R-SAJU-REL-044", "decisionRuleId": "R-SAJU-UN-036" },
          { "type": "육합", "from": "daeun", "with": "hourBranch", "a": "오", "b": "미", "ruleId": "R-SAJU-REL-015", "decisionRuleId": null }
        ],
        "triples": [], "hapPulim": [ ... ] },
      ...
    ],
    "years": [
      { "year": 2026, "daeunIndex": 2,
        "chars": [ { "pos": "stem", "char": "병", "hanja": "丙", ... "share": { ..., "total": -10 } },
                   { "pos": "branch", "char": "오", "hanja": "午", ... "share": { ..., "total": -15 } } ],
        "delta": -25, "line": { "value": -33, "clamped": false },
        "relations": [
          { "type": "천간합", "from": "seun", "with": "monthStem", "a": "병", "b": "신", "ruleId": "R-SAJU-REL-003", "decisionRuleId": null },
          ...
        ],
        "withDaeun": [], "triples": [],
        "hapPulim": [
          { "kind": "existing", "domain": "jiji", "pair": ["오", "미"], "status": "broken_by_dong",
            "reasonCode": "branch_hap_broken", "params": { "incoming": "오", "origin": "seun" },
            "triggeredBy": { "origin": "seun", "value": "오" },
            "reasonFallback": "동기 오(seun) 도래 → 합반 깨짐" },
          { "kind": "new", "domain": "cheongan", "pair": ["병", "신"], "chartValue": "신", "incomingValue": "병", "incomingOrigin": "seun",
            "reasonCode": "new_stem_hap", "params": { "incoming": "병", "origin": "seun", "partner": "신" },
            "reasonFallback": "병(seun) + 원국 신 → 새 천간 합 형성" },
          ...
        ],
        "ipchunNote": false },
      ...
    ],
    "months": [
      { "index": 1, "startsAt": "2026-02-04T04:55:00+09:00",
        "chars": [ { "pos": "stem", "char": "경", ... }, { "pos": "branch", "char": "인", ... } ],
        "delta": 4,
        "relations": [ { "type": "반합", "from": "wolun", "with": "yearBranch", "a": "인", "b": "오", "ruleId": "R-SAJU-REL-024", "decisionRuleId": "R-SAJU-UN-035" }, ... ] },
      ...
    ],
    "compatInputs": {
      "primaryYongshin": "토",
      "surfaceElementCounts": { "목": 0, "화": 2, "토": 2, "금": 3, "수": 1 },
      "surfaceAbsent": ["목"],
      "hourKnown": true,
      "ruleIds": ["R-SAJU-COMPAT-008", "R-SAJU-COMPAT-009", "R-SAJU-COMPAT-010"]
    },
    "caveats": ["R-SAJU-UN-028", "R-SAJU-PRAC-026", "R-SAJU-UN-034"],
    "birthBeforeIpchun": false,
    "assumedLocation": { "correction": "none" },
    "costPoints": 0
  }
}

欄位閱讀方式

• line：累積值 — 大運為命盤 + 大運，流年為命盤 + 當年大運 + 流年。每個階段截斷在 ±100，被截斷時為 clamped: true（R-SAJU-UN-033）。流月沒有累積線，只提供該月運勢的分數（delta）。
• share：單一干支分數的拆解（生扶·剋洩·藏干·通根）。各層權重為大運·流年·流月 1:1:1（R-SAJU-UN-030），運勢地支的通根沒有上限（R-SAJU-UN-031）。
• shinRole：該干支五行的五神名稱（用神·喜神·忌神·仇神·閑神，R-SAJU-YONG-170）— 是名稱而非分數。所有命盤都會附上五神表（不會是 null）。
• relations：運勢干支與命盤干支之間的刑沖會合清單（不計入分數）。ruleId 是配對表規則，decisionRuleId 是同樣適用於運勢的依據規則（UN-035 流月、UN-036 自刑、UN-037 半合）。withDaeun 為流年 ↔ 當年大運。時柱不詳時，不產生與時柱的關係。
• triples：大運·流年干支加入後，與命盤一起湊滿三合·方合三個字的情況（R-SAJU-UN-037）。
• hapPulim：大運·流年干支所觸動的命盤合（合起·解開·破壞）以及新結成的合（R-SAJU-HAP-021~027）。不含流月。畫面文字請依 reasonCode 與 params（incoming 進入的運勢干支、origin daeun|seun，必要時 target·partner）配合應用程式語言自行組成。reasonFallback 一律附有引擎撰寫的韓文句子，僅在應用程式收到不認識的 reasonCode 時作為替代顯示之用。reasonCode 目前有 7 種。
  • stem_hap_kept_jaenghap：命盤的天干合維持不變，相同陽干的運勢干支（incoming）因爭合而無法介入。
  • stem_hap_kept_tuhap：命盤的天干合維持不變，相同陰干的運勢干支（incoming）因妒合而無法介入。
  • branch_hap_gi：運勢干支（incoming）沖命盤六合中的一字（target），使合發動（合起）。
  • branch_hap_released：運勢干支（incoming）刑命盤六合中的一字，使合解開。
  • branch_hap_broken：與命盤六合中一字相同的字（incoming）以運勢進入，使合破壞。
  • new_stem_hap：運勢天干（incoming）與命盤中未成合的天干（partner）結成新的天干合。
  • new_branch_yukhap：運勢地支（incoming）與命盤地支（partner）結成新的六合。
• startAge：大運數（第一步大運的年齡）。日數從出生日（韓國日期）0 時起算到交節為止，不計入出生的時·分，以 3 日 = 1 年四捨五入（R-SAJU-UN-038）。自 kbVersion 2026.10.11-2 起收錄於規則清冊。
• ipchunNote：查詢時點（韓國時間）在當年立春之前時，僅今年的格為 true。表示 1 月 1 日~立春前仍延續前一年的流年。流年採用當年立春的干支（R-SAJU-UN-016）。
• birthBeforeIpchun：於 1 月 1 日~立春前出生，命盤年柱為前一年干支時為 true（最上層欄位）。
• assumedLocation（自 saju-flow-5 起，最上層欄位）：未傳送位置時計算所用的預設值。目前與萬年曆相同，為 { "correction": "none" }（不做真太陽時校正）。萬年曆的預設值改為代表經度時，會回傳 { "correction": "trueSolarTime", "longitude": … }。有傳送位置（birthLatitude·birthLongitude 或 country）時為 null。
• natalAmbiguous：時刻不詳且出生日有交節時為 { "pillar": "month" | "year", "termAt" } — 表示引擎以正午判定，月柱（若為立春則連年柱）可能與實際不同。
• compatInputs：多人疊加比較時，讓應用程式只需做集合交集的值（用神五行、外顯干支的五行數量、外顯中看不到的五行）。不提供人與人之間的加總·排名。

價格

• 銷售關閉時回傳 404 saju_flow_not_enabled（不計費）。
• 僅在計算成功時扣款。輸入錯誤（400 — 不存在的日期、範圍超過 101 年等）與 409 不計費。回應的 costPoints 為本次扣款金額（₩），用量紀錄的 endpoint 為 saju-flow。

錯誤代碼

除了通用錯誤（401、400 本文檢查、402、429、503 等）之外，此 API 會回傳的代碼：

合盤 API

根據兩人的八字計算合盤。一次呼叫即回傳八字合盤（日柱 60×60 合盤表、依用途的分數與 6 軸、天干／地支關係、八字五行互補、十神、交叉神煞）、親密合盤符號表（參考文獻（1995）男女日柱表的符號與等級）、星座合盤（太陽、月亮、上升星座 3 層 + 依用途的行星，星座合盤段落最多 2 段）、生肖合盤（兩個生肖地支的關係與等級），並一併提供將五種分數依用途權重合併的綜合分數（headerBreakdown）。自 2026-10-16 起，也會回傳依位置彙整兩個命盤（原局）之間合、沖、刑、害、破等關係的關係表（relations）及其分數（p2Score）。與 INTA 應用程式合盤畫面使用相同引擎，相同輸入永遠得到相同結果。

INTA 應用程式畫面上的代表分數（大數字）= headerBreakdown.average（下方回應範例中為 62）。saju.score.total（範例中為 59）只平均日柱表與八字，是 HRUM 自有的分數，因此與畫面上的數字不同。

與 INTA 應用程式結果畫面 6 軸圖相同的值是 saju.iljuAxes（saju.axes 是依用途重新計算的另一組值）。知道出生時間的人，須如建議呼叫一併傳送 personXCountry + personXBirthTimePrecision: "exact"，才會以與 INTA 應用程式相同的八字（真太陽時校正）計算。

POST /api/v1/partners/v1/compat

根據兩人的八字分析合盤。

請求參數

details、flow、MBTI 選項不另收費（每次呼叫仍為 ₩20）。

• 時間校正：一個人的八字（日柱、八字分數、綜合分數、親密合盤符號表、生肖、權威分析、yearFlow、關係描述）只計算一次，所有項目共用。未傳送座標、personXCountry、精確度 exact 時，以輸入時間原樣計算（與萬年曆 API 相同）。若需要與 INTA 應用程式（韓文、直接輸入時間）相同的合盤，請為兩人都傳送 personXCountry: "KR"（+ personXBirthTimePrecision: "exact"）— 見下方建議呼叫。沒有出生時間的人不做校正。預設值（不傳送則不校正）不會改變。
• 2026-10-11 變更：傳送座標時，八字也會做真太陽時校正（之前只用於星座合盤）。這是為了讓同一回應中的八字與星座使用相同時間基準所做的修正，因此原本有傳送座標的呼叫，八字分數、日柱可能改變。新欄位以及未傳送座標的呼叫，回應維持不變。
• 日柱為代碼值：saju.personA.ilju、saju.personB.ilju 的值（계미 等）不論 lang 為何，都以韓文干支代碼值輸出。畫面上要顯示的名稱，請改用萬年曆 API 的術語表（glossary）或漢字寫法（癸未，英文、泰文為 癸未 (Gye-mi)）。

建議呼叫（與 INTA 應用程式相同結果）

對知道出生時間的人，請一併傳送出生國家與 "exact"。真太陽時校正會與 INTA 應用程式一致，即使出生時間接近時辰交界，日柱、分數也會與應用程式相同。

{
  "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
  "personACountry": "KR", "personABirthTimePrecision": "exact",
  "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
  "personBCountry": "KR", "personBBirthTimePrecision": "exact",
  "purpose": "yeonae_attraction", "details": true
}

回應範例

以下是實際引擎輸出（A 男 1990-09-04 14:30，B 女 1992-02-20 10:15，戀愛，無座標）。2026-10-10 新增的必定包含欄位（saju.relationRatings、saju.meetingKeywords、saju.authority、tti.conflictFrame）在此範例中省略 — 請見下方選項範例。這兩人即使以建議呼叫（KR + exact）傳送，值也相同。

{
  "success": true,
  "data": {
    "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
    "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
    "tti": {
      "userTti": "말", "partnerTti": "원숭이",
      "relation": { "type": null, "detail": null, "relations": [] },
      "tier": "흉"
    },
    "saju": {
      "purpose": "yeonae_attraction",
      "hourKnown": { "a": true, "b": true },
      "personA": { "ilju": "임신" },
      "personB": { "ilju": "병인" },
      "score": { "total": 59, "grade": "맞춰 가면 좋아요",
                 "breakdown": { "ilju": 53, "authority": 65, "eightChar": 65 } },
      "axes": { "attraction": 25, "stability": 59, "growth": 58,
                "communication": 24, "passion": 74, "longevity": 65 },
      "pattern": { "name": "폭발형",
                   "description": "에너지가 크게 부딪히는 뜨거운 관계예요. 감정이 커질 때 잠시 쉬어 가는 규칙이 도움이 돼요." },
      "relation": { "summary": "천간충 + 인신충",
                    "stem": { "type": "천간충", "detail": "병임충" },
                    "branches": [ { "type": "지지충", "detail": "인신충" } ] },
      "elements": { "basis": "eight", "aLacks": [], "bProvidesToA": [], "bLacks": ["토"], "aProvidesToB": ["토"] },
      "tenGods": { "aView": "편재", "bView": "편관(칠살)" },
      "bestFor": ["단기 끌림"],
      "weakFor": ["결혼·동거"],
      "highlights": [ "상대의 시지에 나의 천을귀인 (사) 발현 — 상대가 나의 해결사" ],
      "iljuAxes": { "attraction": 45, "stability": 16, "growth": 88,
                    "communication": 60, "passion": 70, "longevity": 50 }
    },
    "categoryNarrative": {
      "category": "romantic", "purpose": "yeonae_attraction", "lang": "ko",
      "text": "상대 쪽의 즉각적인 열정과 나 쪽의 자유로운 흐름은 불과 물처럼 정면으로 맞부딪혀서, 처음 만났을 때의 팽팽한 긴장감이 곧 끌림이 되기 쉬워요. 짧고 뜨거운 설렘이 큰 관계라, 감정이 치솟는 날엔 하루쯤 식힐 틈을 두면 더 즐겁게 만날 수 있어요.",
      "styleVersion": "v2"
    },
    "costPoints": 20,
    "classic1995": {
      "symbol": "××", "grade": "대흉", "score": 50,
      "ttiRelation": { "type": null, "detail": null, "relations": [] },
      "conflictFrame": false
    },
    "relations": [
      { "positions": ["month", "month"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "stemChung", "tier": "clash",
        "ruleIds": ["R-SAJU-REL-008", "R-SAJU-COMPAT-110"], "chars": ["壬", "丙"] },
      { "positions": ["year", "year"], "kind": "napeumSaeng", "tier": "gather",
        "ruleIds": ["R-SAJU-BASE-037", "R-SAJU-COMPAT-111"], "chars": ["庚午", "壬申"] },
      { "positions": ["chart", "chart"], "kind": "banghap", "tier": "gather",
        "ruleIds": ["R-SAJU-REL-021", "R-SAJU-COMPAT-104"], "chars": ["巳", "午", "未"] }
    ],
    "p2Score": 57,
    "astroSynastry": {
      "self": {
        "sun": { "signEn": "Virgo", "element": "earth", "modality": "mutable" },
        "moon": { "signEn": "Pisces", "element": "water", "modality": "mutable", "uncertain": false },
        "ascendant": { "signEn": "Sagittarius", "element": "fire", "modality": "mutable", "uncertain": false, "countryBasis": true },
        "venus": { "signEn": "Leo", ... }, "mars": { "signEn": "Gemini", ... },
        "mercury": { ... }, "jupiter": { ... }, "saturn": { ... }
      },
      "partner": { "sun": { "signEn": "Pisces", ... }, "moon": { "signEn": "Virgo", ... }, ... },
      "layers": [
        { "key": "sun", "relation": "opposite", "selfSign": "Virgo", "partnerSign": "Pisces",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "moon", "relation": "opposite", "selfSign": "Pisces", "partnerSign": "Virgo",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "ascendant", "relation": "neutral", "selfSign": "Sagittarius", "partnerSign": "Taurus",
          "textKey": "compat.astro.relation.neutral",
          "text": "뚜렷한 결 없이 각자의 스타일을 존중하면 되는 조합이에요" }
      ],
      "purposeBodies": [
        { "body": "venus", "relation": "opposite", "selfSign": "Leo", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "body": "mars", "relation": "same_element", "selfSign": "Gemini", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.same_element",
          "text": "같은 원소 — 서로의 방식을 바로 알아볼 만큼 편안할 수 있어요" }
      ],
      "caveats": ["compat.astro.caveat.ascendantCountryBasis"],
      "caveatTexts": ["상승궁은 출생 도시가 없어 국가 대표 좌표로 추정했어요"],
      "score": 64
    },
    "astroReadings": [
      { "key": "Su_Mo_ss", "lang": "ko",
        "text": "한쪽의 태양과 다른 쪽의 달이 같은 별자리에 놓이면, 한 사람이 향하는 방향을 다른 사람의 마음이 낯설지 않게 알아보는 깊은 공명이 생기기 쉬워요. 닮은 만큼 같은 그림자도 함께 커질 수 있으니 서로의 빈틈을 웃으며 짚어 주면 좋아요." },
      { "key": "Ve_Ma_op", "lang": "ko",
        "text": "한쪽의 금성과 다른 쪽의 화성이 정반대 별자리에 놓이면, 서로에게 없는 매력을 알아보며 끌리는 보완의 흐름이 생기기 쉬워요. 원하는 속도와 표현 방식이 반대로 기울 수 있으니 서로의 선을 말로 정해 두면 그 끌림이 편안하게 이어져요." }
    ],
    "headerBreakdown": {
      "sixAxis": 55, "authority": 65, "full8": 65, "classic": 57, "natal": 64,
      "average": 62, "purpose": "yeonae_attraction",
      "weights": { "sixAxis": 0.2, "authority": 0.3, "full8": 0.2, "classic": 0.1, "natal": 0.2 }
    },
    "engineVersion": "compat-2",
    "lang": "ko"
  }
}

• saju（八字合盤）是主體。少數無法計算日柱的情況為 null — 此時只顯示 tti
• saju.score.total：0~100。日柱合盤表分數與八字分析分數的平均（各自在 breakdown 中）。grade 是易懂的等級文字 — 아주 잘 맞아요（非常合，85 以上）、잘 맞아요（很合，75 以上）、무난해요（還可以，65 以上）、맞춰 가면 좋아요（互相配合會更好，55 以上）、서로 많이 달라요（彼此差異很大）。此值與以往相同 — 包含符號表、星座的分數是 headerBreakdown.average
• saju.axes：吸引、穩定、成長、溝通、熱情、持久 6 軸（0~100），依 purpose 而異。saju.pattern：關係類型名稱與說明（無則為 null）
• saju.iljuAxes（2026-10-27~）：與 INTA 應用程式結果畫面 6 軸圖相同的值 — 直接採用兩人日柱組合在合盤表中的 6 軸（attraction、stability、growth、communication、passion、longevity，0~100，與 purpose 無關）。6 軸平均即 headerBreakdown.sixAxis。鍵與 saju.axes 相同，但計算方式不同，數字也不同。合盤表中沒有該組合時為 null
• saju.elements：以兩人整個命盤（不知時間則為 6 字 — basis: "six"）的五行分布計算。bProvidesToA = A 缺少的五行中 B 擁有的部分
• saju.tenGods：以 A 為基準看 B 的十神（aView）及其反向（bView）。highlights：從八字中找到的交叉神煞句子（最多 5 句，無則為空陣列）
• relations（2026-10-16~）：兩個命盤之間的關係清單。檢視同一位置的地支組合（年、月、日、時 — 時柱只在兩人都有出生時間時）、日干之間的天干合、天干沖、年柱納音五行，以及需合併兩個命盤才成立的三合、方合。每個項目有 positions（[A 方, B 方] — year、month、day、hour，三合、方合為 chart = 整個命盤）、kind（見下表）、tier、ruleIds（依據的 KB 規則 ID — 可在 KB API 查看原典出處）、chars（關係字，漢字）。所有鍵都與語言無關，改變 lang 也相同。畫面文字請依 kind 自行製作。沒有好壞的判定詞。無法建立命盤時為 null，完全沒有關係時為空陣列
• tier：gather 聚合（合的一方）、clash 相違、heavyClash 重度相違（原典載明較重的關係，目前為沖）、listOnly 僅列出（原典中找不到方向依據、不計入分數的關係）
• p2Score（2026-10-16~）：0~100。將 round(71.6 + 5 × Σ) 截在 0~100 的值 — Σ = 每個關係依 gather +1、clash −1、heavyClash −2、listOnly 0 加總。1 單位 = 5 分，71.6 是完全沒有關係時的中立點（先前原典軸分數的實際會員平均，以 2026-10-16 為準）。有無時柱都使用相同尺度。原典只說明關係的方向與順位，未說明大小 — 這個數字是畫面顯示用的尺度假設，不是原典的分數（KB R-SAJU-COMPAT-113）。relations 為 null 時為 null
• classic1995 （預計停止支援）：目前仍與以往完全相同地回傳。停止時程（草案）：2026-11-16 公告 → 維持至 2026-12-31 → 2027-01-01 起為 null。日期可能依營運公告調整。新串接請使用 relations、p2Score。參考文獻（1995）男女日柱親密合盤表的符號（● 대길（大吉）100、◎ 중길（中吉）90、○ 길（吉）80、△ 무해무덕（無害無德）70、× 흉（凶）60、×× 대흉（大凶）50）。此表是男方日柱 × 女方日柱的方向表，同性或未傳送性別時會讀取兩個方向（A 為男方、B 為男方），score 為兩個分數的平均（例 95），symbol、grade 則是將該平均以 10 分為單位無條件捨去後的等級（例 95 → ◎ 중길）。兩個方向相同時直接使用該符號。conflictFrame：符號為吉但生肖關係為凶，或相反時為 true。無法求得日柱時整體為 null
• astroSynastry：星座合盤。layers = 太陽、月亮、上升星座 3 層比較，purposeBodies = 依用途的優先行星（戀愛：金星、火星，婚姻：+土星，友情：水星、木星 …）。relation = same_sign、opposite、same_element、element_support、same_modality、element_friction、neutral，text 是其含義解讀（lang）。score 0~100。caveats/caveatTexts：上升星座、月亮星座為推估時說明此事。不知時間時會省略上升星座層
• astroReadings：針對兩人星座中最突出的交點（太陽–月亮、金星–火星等）最多 2 個，事先寫好的解讀段落。無則為空陣列。各段落的 lang 是實際文字語言（沒有請求語言的文字時為 ko）
• headerBreakdown：將 6 軸平均、權威（authority）、八字（full8）、原典部分（classic — 自 2026-10-16 起為 p2Score，之前為 classic1995.score）、星座（natal）五個分數，依 purpose 別權重（weights）合併的綜合分數 average（0~100）。缺少的分數由其餘分數重新分配權重。與 INTA 應用程式合盤畫面的代表分數（大數字）相同（上例為 62）。自 2026-10-16 起，婚姻用途（marriage_stability）的原典部分（classic）權重由 0.25 降為 0.05，減少的 0.20 依先前比例分給其餘四軸（sixAxis 0.15 → 0.19、authority 0.25 → 0.3167、full8 0.25 → 0.3167、natal 0.10 → 0.1267）。其他用途的權重不變。找不到日柱合盤表時為 null
• 出生年份須在 1900~2100 — 超出範圍回傳 400 INVALID_BIRTH_YEAR（不計費）。在日期輸入欄位只輸入兩位數年份時會變成 0090 這樣，請在畫面上也加以阻擋。在合盤表中找不到結果時回傳 400 COMPAT_UNAVAILABLE（不計費）
• tti.tier：參考文獻（1995）生肖合盤的等級字串（例：대길、길、중길、보통、주의、흉 — 從大吉到凶）。tti.relation.type = 兩個生肖地支的關係 — 충（沖）、원진（怨嗔）、형（刑）、해（害）、육합（六合）、반합（半合）、파（破）其中之一（多個關係重疊時取此順序中較前者），無則為 null。detail 只在半合時出現（例：수국(水局)）。tti.relation.relations = 所有重疊的關係（相同順序，例：牛、羊生肖 ["충","형"]，無則為空陣列）
• tti 只回傳生肖、關係、等級。不收錄參考文獻的生肖合盤文句（自 2026-10-11 起）。
• categoryNarrative：說明兩人在此關係（purpose）中狀況的 2~3 句話。這些是依兩人日柱組合（1,830 對）與 6 種關係類型事先寫好的句子，相同輸入永遠得到相同句子。句中的 나 = A，상대 = B（英文 You/Your partner，日文 あなた/相手，泰文 คุณ/คู่ของคุณ）。可透過 lang 選擇 4 種語言，找不到句子時為 null（計費相同）
• 必定包含（2026-10-10~）：saju.relationRatings = 5 種關係各自的 { key, stars }（key 例：연애（戀愛）、결혼·동거（婚姻、同居）、친구（朋友）、사업 파트너（事業夥伴）、장기 관계（長期關係）／星等 1~5）、saju.meetingKeywords = 相遇關鍵字 3 個、saju.authority = 權威合盤判定（finalScore、grade、gradeTier、pattern、summary、levels（L1~L4）、factors、flags、climateBalance）、tti.conflictFrame = 與 classic1995.conflictFrame 相同的值
• yearFlow.years[].tier：great、good、neutral、caution。dayFlow.days[].tier：golden、good、neutral、dim、hard（dayFlow.golden/hard 為對應的日期清單）

關係類型（relations[].kind）

相同的 kind 一律對應相同的 tier（只有破的兩組例外）。之後可能新增 kind，請讓程式略過不認得的值。

選項範例（details · flow · MBTI）

實際引擎輸出節錄。請求：

{
  "personABirthDate": "1990-05-15", "personABirthTime": "12:00", "personAGender": "male",
  "personBBirthDate": "1992-08-20", "personBBirthTime": "09:00", "personBGender": "female",
  "details": true, "flow": true, "date": "2026-10-10",
  "personAMbti": "ENFP", "personBMbti": "ISTJ"
}

{
  "success": true,
  "data": {
    "tti": { "userTti": "말", "partnerTti": "원숭이", ..., "tier": "흉", "conflictFrame": false },
    "saju": {
      "personA": { "ilju": "경진" }, "personB": { "ilju": "무진" },
      "score": { "total": 56, "grade": "맞춰 가면 좋아요", ... },
      ...,
      "relationRatings": [
        { "key": "연애", "stars": 3 }, { "key": "결혼·동거", "stars": 3 }, { "key": "친구", "stars": 4 },
        { "key": "사업 파트너", "stars": 3 }, { "key": "장기 관계", "stars": 3 }
      ],
      "meetingKeywords": ["괴강", "우직", "일반적 관계"],
      "authority": {
        "finalScore": 51, "grade": "주의", "gradeTier": "caution",
        "pattern": "자형 (자기 갈등 외부화)",
        "summary": "주의 · 자형 (자기 갈등 외부화) · 익숙한 결의 만남. 안락함 위에 자극을 어떻게 만들지가 핵심.",
        "levels": { "L1": { "raw": 0, "norm": 0 }, "L2": { "raw": 5, "norm": 14.3, "type": "동계절 (봄)" },
                    "L3": { "raw": 17, "norm": 56.7 }, "L4": { "raw": -17, "norm": -42.5 } },
        "factors": { "l1": [], "l2Tone": "...", "l3": [ ... ], "l4": ["자형(진진) — 자기 파괴 패턴", ...] },
        "flags": { "cheonHapJiHap": false, "dualChung": false },
        "climateBalance": "동계절 (봄)"
      },
      "conflict": {
        "pattern": "경은 무를 편인으로 인식. 일방향적 관계 성격.",
        "tip": "'괴강'과 '우직'은 서로 다른 결이에요. 같은 사건도 다르게 해석한다는 걸 인정하고, 서로의 관점을 한 번씩 빌려보세요."
      },
      "relationScores": { "stem": { "type": "편인", "category": "neutral", "score": 55 },
                          "branches": [ { "type": "자형", "score": -40 } ] },
      "full8": { "personA": { ... }, "personB": { ... }, "iljuEvaluation": { ... }, ... }
    },
    ...,
    "dictionary": { "a": { "id": "ilju_경진", "name_kr": "경진", "name_hanja": "庚辰", ... }, "b": { ... } },
    "yearFlow": {
      "baseYear": 2026,
      "years": [
        { "year": 2024, "score": 77, "tier": "great", "a": { ... }, "b": { ... },
          "summary": "두 분 모두 흐름이 좋아 같이 시작하기 좋은 해." },
        ...
      ]
    },
    "dayFlow": {
      "baseDate": "2026-10-10",
      "days": [
        { "date": "2026-10-03", "a": -89, "b": -40, "combined": -60, "tier": "hard", "isBaseDate": false },
        ...,
        { "date": "2026-10-10", "a": -9, "b": 27, "combined": 9, "tier": "neutral", "isBaseDate": true },
        ...
      ],
      "golden": [],
      "hard": [ { "date": "2026-10-03", "combined": -60 }, ... ],
      "summary": "3번 같이 가라앉는 날이 있어. 그날은 큰 결정·약속 미루자."
    },
    "mbti": { "id": "mbti_ENFP_ISTJ", "mbti_a": "ENFP", "mbti_b": "ISTJ",
              "socionics_relation": "Duality(이중관계)", "scores": { ..., "total": 64 }, ... }
  }
}

注意事項

• 基本資訊：兩人的出生日期為必填。時間與性別為選填。即使沒有性別或性別相同，也會提供親密合盤符號表（合計兩個方向）；星座合盤的上升星座則需要出生時間。
• 結果組成：星座合盤以回歸黃道為準。各關係的描述以 categoryNarrative、星座段落以 astroReadings 一併回傳；若需要更長的客製解讀，請將結果放入 /reading 的提問中使用。
• 2026-10-16 變更（engineVersion compat-2）：新增 relations · p2Score · engineVersion，且 headerBreakdown.classic 改為 p2Score，因此 headerBreakdown.average 可能與以往不同（與 INTA 應用程式合盤畫面相同的值）。其他既有欄位的值不變。
• 相容性：2026-10 新增的欄位（classic1995 · astroSynastry · astroReadings · headerBreakdown · lang，以及 2026-10-10 的 saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame）無論是否傳送 lang 都會附加。既有欄位的值不變。但自 2026-10-11 起，轉載參考文獻（1995）文句的欄位 — 生肖合盤一句話解讀，以及日柱辭典中的愛情運、健康運 — 已從回應中移除。
• 2026-10-27 新增：新增 saju.iljuAxes（必定包含，位於 saju 區塊最後）。既有欄位的值與順序不變，engineVersion 也維持 compat-2。
• 2026-10-31 變更：修正合盤韓文句子中的助詞，使其符合前一字的收尾音（例：「임와」 → 「임과」、「병는」 → 「병은」）。鍵、順序、數字與其他語言的句子不變。
• 費用：每次呼叫扣除 ₩20（包含新增欄位、details、flow、MBTI 選項，不另收費）。

錯誤代碼

除了共通錯誤（401、400 內文檢查、402、429、503 等）之外，此 API 會出現的代碼：

請求範例請見上方選項範例與執行範例。

性格類型 API

提供以 MBTI 為基礎的性格測驗。支援免費精簡版（24 題）與進階版（93 題）。

GET /api/v1/partners/v1/personality-type/questions

查詢性格測驗題目。免費。

curl "https://api.hrum.ai/api/v1/partners/v1/personality-type/questions?tier=free" \
  -H "X-Partner-Api-Key: your-api-key"

請求參數

回應範例

{
  "success": true,
  "data": {
    "tier": "free",
    "count": 24,
    "questions": [
      {
        "id": "q_001",
        "text": "갑자기 생긴 모임에도 일단 가본다",
        "choices": [
          { "value": 1, "label": "전혀 그렇지 않다" },
          { "value": 2, "label": "그렇지 않다" },
          { "value": 3, "label": "보통이다" },
          { "value": 4, "label": "그렇다" },
          { "value": 5, "label": "매우 그렇다" }
        ]
      }
    ]
  }
}

POST /api/v1/partners/v1/personality-type

提交性格測驗的答案，分析性格類型。

curl -X POST https://api.hrum.ai/api/v1/partners/v1/personality-type \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "free",
    "answers": [
      { "questionId": "q_001", "answer": 4 },
      { "questionId": "q_002", "answer": 2 }
    ]
  }'

請求參數

回應範例

{
  "success": true,
  "data": {
    "personalityType": "ENTJ",
    "typeLabel": "지휘관",
    "scores": {
      "extraversion": 72,
      "sensing": 45,
      "thinking": 68,
      "judging": 80
    },
    "tier": "premium",
    "costPoints": 10
  }
}

價格

• 免費版（free）：24 題，₩0（免費）
• 進階版（premium）：93 題，₩10/次
• 不存在的 questionId 或 1~5 以外的 answer 會回傳 400，不計費。
• 在 premium 中若有完全沒有答案的軸，回傳 400 personality_axis_unanswered，不計費。回應的 axes 會列出空白的軸（E_I · S_N · T_F · J_P）。

錯誤代碼

除了共通錯誤（401、400 內文檢查、402、429、503 等）之外，此 API 會出現的代碼：

答案在 1~5 以外時為共通 400。以上皆不計費。

解讀資料庫（KB）API

僅對已申請的帳號開放的 API。未開放的帳號在三個路徑都會收到 404 kb_saju_explain_not_enabled（不計費）。如需使用，請透過支援洽詢。

將八字命盤中成立的關係（合、沖等）與結構（十神、藏干等）以規則卡與解說文字說明。不使用 LLM，相同輸入永遠得到相同結果。

POST /api/v1/partners/v1/kb/saju/explain

請求參數

請求範例

curl -X POST https://api.hrum.ai/api/v1/partners/v1/kb/saju/explain \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "year": 1990, "month": 5, "day": 17, "hour": 14, "minute": 30,
      "timezone": "Asia/Seoul", "gender": "female"
    },
    "sections": ["relations"]
  }'

回應範例（節錄）

{
  "success": true,
  "data": {
    "kbVersion": "2026.10.09-3",
    "kbHash": "sha256:24b9a2d9...",
    "channel": "stable",
    "chart": {
      "pillars": {
        "year":  { "stem": "庚", "branch": "午" },
        "month": { "stem": "辛", "branch": "巳" },
        "day":   { "stem": "壬", "branch": "午" },
        "hour":  { "stem": "丁", "branch": "未" }
      },
      "timeUnknown": false
    },
    "sections": [
      {
        "id": "relations",
        "title": "...",
        "steps": [
          {
            "fact": { "type": "stem_pair", "a": "壬", "b": "丁", "posA": "day", "posB": "hour", "relation": "hap" },
            "factText": "일간 壬과 시간 丁은 천간합(天干合) 관계다.",
            "componentId": "saju:stem_pair:丁壬:hap",
            "rules": [
              { "id": "R-SAJU-REL-004", "kind": "definition", "status": "verified", "sourceCount": 2,
                "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다." }
            ],
            "interp": {
              "meaning": { "text": "丁(정)과 壬(임)은 천간합으로 묶이는 짝이고, ...", "reviewed": false },
              "why": { ... },
              "pitfall": { ... }
            }
          }
        ],
        "absent": [
          { "type": "stem_pair", "a": "庚", "b": "辛", "posA": "year", "posB": "month",
            "note": "庚과 辛은 천간합·천간충 어느 것도 아니다." }
        ]
      }
    ],
    "unregistered": [],
    "pendingReview": []
  }
}

• interp 是解說欄位（meaning 含義、why 依據、pitfall 注意）。每個欄位為 {text, reviewed, reviewedBy?, notes?}，在 stable 中只會出現已審核的欄位。
• unregistered：已成立但尚無解說的項目。pendingReview：有解說但尚未審核，因此在 stable 中隱藏的項目。
• 規則卡的原典出處可透過下方 GET /kb/rules/{id} 查詢。

GET /api/v1/partners/v1/kb/rules/{id}

回傳單一規則卡與原典出處。免費。

curl https://api.hrum.ai/api/v1/partners/v1/kb/rules/R-SAJU-REL-004 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "id": "R-SAJU-REL-004",
    "kind": "definition",
    "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다.",
    "status": "verified",
    "schools": [],
    "variantOf": null,
    "sources": [
      { "sourceId": "SRC-SMTH", "location": "『三命通會』 卷二 論十干化氣",
        "quote": "故丁與壬合　丁壬化木", "match": "EXACT", ... }
    ],
    "engineRef": "..."
  }
}

GET /api/v1/partners/v1/kb/release?domain=saju

回傳目前公開的解讀資料庫版本。免費。domain 省略時為 saju（例：saju · ziwei · astro · dream · tarot）。

curl "https://api.hrum.ai/api/v1/partners/v1/kb/release?domain=saju" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "version": "2026.10.09-3",
    "hash": "sha256:24b9a2d9...",
    "publishedAt": "2026-10-09T00:00:00.000Z",
    "channel": "stable",
    "counts": { "rules": 412, "interps": 1236 }
  }
}

上方數字為範例。若您會儲存結果，請在 hash 改變時重新取得。

錯誤代碼

除了共通錯誤之外：