開發者入門指南

這是第一次串接 HRUM 八字 API 的步驟。從註冊、第一次呼叫、計費到錯誤處理，照著這一頁做就可以。各端點的完整參數請見 API 文件。

想在註冊前先看看結果嗎？在 Playground 不需要金鑰，每月可免費試用 5 次。

交給 AI 打造應用程式 — 免費電子書（韓文）

選擇電子書（韓文）整合運勢應用程式（韓文）角色聊天應用程式（韓文）會員制網頁應用程式（韓文）

1. 註冊主控台

  1. 在 主控台登入畫面 選擇 註冊 分頁，輸入電子郵件與密碼。
  2. 打開收件匣中的驗證信，按下驗證按鈕後再登入一次。
  3. 註冊後會獲得免費點數 ₩1,000（若觸發防止不當註冊的條件，發放可能會暫緩）。

2. 核發 API 金鑰

  1. 在主控台的 API 金鑰 畫面輸入金鑰名稱（例如：正式環境伺服器），然後按下 核發。
  2. 新金鑰 只在核發後顯示一次。請立即複製，保存在伺服器環境變數等安全的地方。遺失的話請重新核發。
  3. 金鑰只能在伺服器端使用。放進瀏覽器或應用程式的程式碼裡，任何人都能取出來使用。

在同一畫面的 請求限制 設定每秒與每日的請求數上限，即使金鑰外洩或程式無限迴圈，也能保護您的餘額。

3. 第一次呼叫 — 萬年曆

所有請求都送到 https://api.hrum.ai/api/v1/partners/v1/ 底下的路徑，金鑰放在 X-Partner-Api-Key 標頭中。下面是用出生年月日時計算八字命盤（原局）的萬年曆呼叫。

curl

export HRUM_API_KEY="your-api-key"

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

Python (requests)

import os
import requests

res = requests.post(
    "https://api.hrum.ai/api/v1/partners/v1/manseryeok",
    headers={"X-Partner-Api-Key": os.environ["HRUM_API_KEY"]},
    json={"year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
          "timezone": "Asia/Seoul", "gender": "male"},
    timeout=30,
)
body = res.json()
if not body.get("success"):
    raise RuntimeError(f'{body.get("statusCode")} {body.get("code")}')
print(body["data"]["wonkuk"]["day"])

Python 標準函式庫 urllib 的預設 User-Agent 會被安全規則擋下，回傳 403。請改用 requests，或在使用 urllib 時自行加上 User-Agent: <app-name>/<version> 標頭。

JavaScript（Node 18 以上，伺服器端）

const res = await fetch('https://api.hrum.ai/api/v1/partners/v1/manseryeok', {
  method: 'POST',
  headers: {
    'X-Partner-Api-Key': process.env.HRUM_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ year: 1990, month: 5, day: 15, hour: 12, minute: 0, timezone: 'Asia/Seoul', gender: 'male' }),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.statusCode} ${body.code ?? ''}`);
console.log(body.data.wonkuk.day);

4. 讀取回應

成功時會回傳 {"success": true, "data": { … }}。萬年曆的 data 裡有命盤四柱（wonkuk）、五行分布（ohaengBalance）、用神（yongshin）、格局、大運、流年等。完整欄位清單請見 萬年曆 API 文件。

像萬年曆這樣相同輸入就得到相同結果的計算型 API，只要把取得的結果存進資料庫重複使用，就不會再產生費用。

5. 計費與點數

各商品單價請見 價目表。主要計算型商品價格（依目前價目表）：

6. 錯誤處理

錯誤回應的內容格式為 {"success": false, "statusCode": 400, "code": "…", "message": "…", "timestamp": "…"}。請以 statusCode 和 code 判斷分支，不要依賴 message 的文字。

代碼意思處理方式
400請求參數錯誤修正請求。請不要重試同一個請求。
401缺少 API 金鑰或金鑰無效確認標頭名稱（X-Partner-Api-Key）與金鑰值。
402點數餘額不足。code 為 INSUFFICIENT_BALANCE，或在呼叫前不檢查餘額的 API（萬年曆等）中沒有 code儲值後再呼叫一次。
403被安全規則擋下（內容是 HTML 而非 JSON，error 1010）— 預設 User-Agent 被封鎖的 HTTP 用戶端（Python urllib 等）。不是 API 金鑰的問題加上 User-Agent: <app-name>/<version> 標頭。換金鑰也無法解決。
404帳號未開通的功能（*_not_enabled）或不存在的資源不會計費。請確認路徑與功能是否已開通。
422無法處理的輸入（例如：PROMPT_TOO_LONG）縮短或修正輸入。
429超過請求上限有 Retry-After 標頭就等待該時間，沒有的話稍等一下（最多 1 分鐘）再重試。
500 · 503 · 504伺服器錯誤 · 暫時無法使用 · 上游逾時逐步拉長間隔（例如：1 秒 → 2 秒 → 4 秒），只重試幾次。

為了保護服務，每個 API 金鑰一律有每分鐘 300 次的上限。詳細內容請見 錯誤代碼 與 Rate Limit 文件。是否發生故障可在 服務狀態 頁面確認。

下一步

聯絡我們：contact@float.do · 營運：FLOAT Co., Ltd.