APIガイド

このAPIスタックが実際のサービスでどう動くか気になりますか？ 同じエンジンで動くAI四柱推命（サジュ）アプリ INTA – Life is Timing で、四柱推命分析とAIチャットを試せます。 INTAはこのAPIの実稼働リファレンスです。 INTAのAI音声応答（TTS）も同じスタックで動いています — 音声APIは今後提供予定です。

クイックスタート

HRUMは、記憶するAI・四柱推命分析・LLM再販を提供しています。次の3ステップで始められます。

ベースURLは 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）

節約のコツ — 結果を保存して再利用しましょう。 成功したリクエストはすべて個別に課金されます。万歳暦（マンセリョク）・紫微斗数・相性・西洋占星術・生涯四柱の結果は、同じ生年月日時・同じオプションなら毎回同一です。最初のレスポンスをDBに保存し（たとえばリクエスト本文のハッシュをキーにして）、以降は保存した値を使ってください。今日の運勢や運勢フローのように日付で変わる結果は、キーに日付を含めます。詳しくは冪等性をご覧ください。

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字幕の自動挿入にも対応しています。

セッションなし — 終わりのない1つのセッションです。 同じ user で呼び出せば、会話はそのまま続きます。呼び出しのたびにサーバーが直近 historyCount 件の会話ターンと recallCount 件の長期記憶（要約・プロフィール・記憶した事実・継続中の悩み）を自動で付けるので、送るのは新しいメッセージ1件だけです。どこまで遡るかは2つの数値で調整し、memoryCap でエンドユーザーごとの最大保存メッセージ数を設定します。履歴を自分で管理したい場合は、historyCount を省略し、以前の会話をOpenAI方式で messages に入れて送ってください。

会話が長くなってもコストは比例して増えません。 古いアシスタントターンは自動で圧縮されます — 直近2ターンは原文のまま残り、それより前のターンは500文字から200文字へ段階的に短くなり、入力トークンを節約します（ユーザーターンはそのまま）。また、ユーザーが以前の発言について尋ねると（「前に〜って言ってたよね」）、サーバーが保存済みの会話を検索し、日付と話者付きで引用します（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のチャンクではなく、名前付きの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リンクから字幕を抽出し、入力トークンに含めます。字幕を取得できない場合は挿入せずに会話が続き、youtubeUsed は空配列で返ります（単体のYouTube要約APIのみ、課金なしで400を返します）。
• 元のモデルとの互換性： model値がopenai/*・google/*・anthropic/*の場合、メモリー機能なしで元のモデルをそのまま呼び出します（原価 × 為替レート × 1.10）。
• プロンプトキャッシュ割引： OpenAI系モデル（openai/*、ridm/gpt-*）で同じプレフィックス（1,024トークン以上）を繰り返し送ると、アップストリームのキャッシュにヒットした入力トークンは入力単価の30%で課金されます。レスポンスの usage.prompt_tokens_details.cached_tokens と GET /usage/logs の cachedTokens で確認できます。キャッシュがヒットするかは、アップストリームのポリシーにより呼び出しごとに異なる場合があります。Googleモデルにはキャッシュがないため、入力単価が全額適用されます。 Claudeモデルもキャッシュを要求しないため、入力単価が全額適用されます。
• REPORT_ONLY_MODELは対象外： ridm/saju-reportはメモリーなしの単発専用なので、このエンドポイントでは使えません（400）。

カスタムプロフィール

ridm/* モデル専用です。 エンドユーザーごとに任意のフィールド名と値のペアを保存・管理します。自動抽出したフィールド値を保存したり、値を自分で設定したり、特定のフィールドを今回のターンのプロンプトに含めたりできます。値は蓄積され、スキーマが変わっても既存の値は保たれます（soft-update）。

リクエストパラメータ（POST /api/v1/partners/v1/chat/completions）

リクエスト例（RIDMチャット）

{
  "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の値はスキップされて既存の値が保たれます。フィールドが削除されるのは上記の削除APIを使ったとき（または100件を超えて古い順に自動削除されたとき）だけです。endUserProfileで設定した値は抽出値を上書きします。
• 値の長さはリクエストごと： profileValueMaxCharsは保存されず、そのリクエストで保存される値にのみ適用されます。
• Soft Update： スキーマ（フィールド名）が変わっても既存の値は保たれ、呼び出しのたびに新しい値とマージされます。
• ridm/* のみ： 再販モデル（openai/*、google/*）はプロフィールを無視します。

LLM API（再販）

openai/*、google/* などの元のLLMモデルの再販です（メモリーなし、元のレスポンスそのまま）。再販モデルへのリクエストでは、user、systemPrompt、recallCount、memoryCap、summaryEvery、emotion、candor は無視され（システム指示は messages に {"role":"system"} として入れてください）、レスポンスにメモリーフィールド（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 形式ではありません。価格は100万トークンあたりのウォン（₩）で、下の数値は例です。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： 非表示の思考・推論を使うモデルでは、思考トークンも出力上限に含まれます。サーバーは呼び出しに余裕を加えますが、max_tokens が非常に小さい（例：16）と、finish_reason: "length" で本文が空になることがあり、アップストリームで消費したトークンは課金されます。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/ モデルを含む）。

思考の余裕と課金トークン： 思考をオフにできないモデル（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/ モデルを含む）では、確実に回答を得られるよう、サーバーが思考の余裕（最大1,500トークン）を max_tokens に上乗せします。思考トークンは出力単価で課金されるため、実際に課金される出力トークンが max_tokens を超えることがあります（例：max_tokens 200のリクエストで828トークン課金 — 思考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のチャンク形式ではないため、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のエラー表と同じです。再販モデルにも1日の利用上限（RATE_LIMITED）が適用されます。

AI四柱推命リーディングAPI

生成AIが四柱推命（サジュ）の命式を分析し、その人に合わせた解釈とアドバイスを返します。トークン単位で課金され、返すのは解釈だけです。

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が入っています。その日の日柱（今日の気）は、別途呼び出さなくてもすべてのリーディングにデフォルトで反映されます（追加料金なし）。1回の統合呼び出しで、含まれるモジュールの計算結果を根拠としてすべてをまとめて読み解きます。不要なものは exclude で外してください。必要なAIだけを呼び出すには only を使います。計算結果だけが必要なら、同じモジュールを計算用エンドポイント（/ziwei-chart · /astrology（西洋占星術総合） · /dream · /tarot）で1つずつ呼び出し、自分のアプリを作ることもできます。/reading/memory も同じフィールドを受け付けます。

• 課金： 通常のトークン料金（質問＋persona＋含まれるモジュールの根拠ブロックの文字数 × 0.25を入力トークンとし、それに出力トークンを加えたもの）に加えて、含まれるモジュールごとに単体エンドポイント1回分の料金が加算されます。根拠ブロックはそれぞれ1,500文字未満の要約です。アカウントで機能がオフのモジュールや料金のないモジュールは含まれません。モジュールごとの料金と1回あたりの目安は料金ページにあります。
• 四柱（saju）だけを送るリクエストには生年月日がないため、紫微斗数と西洋占星術は含まれません（夢占いとタロットは含まれます）。
• tools.astrology との関係： 西洋占星術モジュールが含まれる場合、同じネイタルチャートが二重に入らないよう、tools.astrology によるチャートの挿入はスキップされます。西洋占星術モジュールを外した場合（exclude または機能オフ）は、tools.astrology が従来どおり動作します。
• 夢占いの安全措置： dream のテキストに危機を示す言葉が含まれる場合はAIを呼び出さず、支援情報（support）を costPoints: 0 で返します。
• 機能スイッチ： 現在オンです。サーバー設定がオフになると、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を1つだけ使う — only

四柱推命AIには、四柱推命・紫微斗数・西洋占星術・タロット・夢占いのAIが入っています。上のような1回の統合呼び出しの代わりに、only で必要なAIだけを呼び出せます。そのAIは自分の根拠（命式・ネイタルチャート・引いたカード・夢の候補）だけで答え、それ以外は加わりません。

• 課金： トークン料金（質問＋persona＋そのAIの根拠ブロックの文字数 × 0.25を入力トークンとし、それに出力トークンを加えたもの）＋そのモジュールの固定料金1件分。分野ごとの1回あたりの目安料金は料金ページにあります。
• exclude とは併用できません： 両方送ると400 ONLY_WITH_EXCLUDE を返します。そのAIに必要な入力がない場合は400 ONLY_REQUIRES_INPUT、アカウントでその機能がオフの場合は400 ONLY_DOMAIN_UNAVAILABLE になります — 四柱推命リーディングに切り替わることはありません。その日付で命盤を計算できない場合は400 ONLY_INPUT_INVALID です。
• tarot と dream には生年月日が不要です。 birth や saju なしで、質問とカード（または夢のテキスト）だけを送ってください。saju 以外の only は四柱推命を使わないため、レスポンスに 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： candor を t で送った場合のみ、レスポンスに実際に適用された率直さ（t | f）が付きます。/reading/memory も同じです（率直さ（仮称））。
• 課金の基準： 入力 =（質問＋personaの文字数）× 0.25トークン（＋/reading で挿入されたYouTube字幕の文字数 × 0.25）、出力 = 実際の生成トークン数。四柱推命データの挿入とシステムプロンプトは課金されず、usage.inputTokens は参考値です。含まれるモジュール（今日の運勢・紫微斗数・西洋占星術・夢占い・タロット）がオンの場合は、その根拠ブロックとモジュールごとの固定料金が加算されます。costPointsが実際に請求された金額です。
• 応答の言語： 韓国語以外の質問には、質問と同じ言語で答えます。
• 出生時刻が不明な場合： hourを省略すると時柱が除かれ、年・月・日の三柱でリーディングします。

AI四柱推命リーディング・メモリーAPI

エンドユーザーごとの会話メモリーをホスティングし、ユーザーが戻ってきたときに過去の文脈を踏まえてリーディングを続けます。継続的でパーソナライズされた相談を提供できます。料金はAI四柱推命リーディングのトークン単価の1.3×です（1Mトークンあたり：入力 KRW 3,754・出力 KRW 30,030 — リーディングは入力 KRW 2,888・出力 KRW 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× の単価：メモリーをホスティングするため、入力・出力のトークン単価はAI四柱推命リーディングの1.3×です（1Mトークンあたり：入力 KRW 3,754・出力 KRW 30,030、VAT別）。
• endUserId は必須：エンドユーザーごとに一意のIDが必要です。同じIDでの呼び出しは過去の文脈を引き継ぎます。
• メモリーの保持：保存されたメモリーは、明示的に削除するまで保持されます。

四柱推命レポートAPI

ボタンひとつ、質問なしで、総評から財運・恋愛・大運まで四柱推命の全体リーディングを一度に提供します。会話型リーディングとは別の単発の有料商品です。デフォルトは専用モデル 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)
  }
}

• 四柱推命の注入は無料：万歳暦の計算と注入、およびシステムプロンプトは課金されません。入力の課金はペルソナの長さのみで、出力は実際に使われたトークン分です。
• 実測コスト：デフォルトの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。
• 課金：トークン単位で、使用したモデル（デフォルト ridm/gpt-5.6-terra）の再販価格そのまま（原価 × 1.1）で課金されます — メモリー層がないため、RIDM Memoryの単価（× 1.3）は適用されません。costPoints = ceil(入力トークン × 入力単価 + 出力トークン × 出力単価)。単価は1Mトークンあたり（VAT別）です。
• 実測コスト：20–30分の動画で1回あたり約60P（トークン込み）。
• リーディングとの併用：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は、パートナーアカウント単位とリクエスト単位でオプトインする方式です。アカウント全体の設定はコンソールの「機能設定」で管理します。リクエスト単位では、チャットはトップレベルの youtube:true、リーディングは tools: { "youtube": true } で有効にします。

• アカウント全体で無効：403 { code: 'FEATURE_DISABLED', feature: 'youtube' } を返します
• リクエスト単位：youtube:true がない、または false = YouTubeを注入しません

ドキュメント処理API

PDF、Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）、CSV、テキスト、Markdown、ハングル（.hwpx）のドキュメントをアップロードし、AIに分析させて、文脈を理解するナレッジベースに取り込みます。テキストは自動で抽出され、「AI分析」オプションをオンにすると、ドキュメントを文脈ごとのセクションに分け、セクションごとに要約と検索用タグを生成して保存します。

対応形式と制限

エンドポイント

ファイルのアップロード

POST /api/v1/partners/v1/files

ファイルをmultipartフォームでアップロードします。

リクエストフィールド

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 completionsまたはAIリーディングのリクエストで、fileIds パラメータを使って最大5件のドキュメントを注入します。分析済みファイルはドキュメントの要約（最大500文字）と原文を注入し、未分析のファイルは原文を注入します（原文は1ファイルあたり最大40,000文字 / 合計80,000文字。子チャンクは注入されません）。注入されたドキュメントは最後のユーザーメッセージに追加され、入力トークンとしてカウントされます。再販モデルは明示的な fileIds の注入のみに対応しています。

自動呼び出し（ridm/* のみ）：ridm/* のチャットモデルとリーディング・メモリーモデルでは、ユーザーの質問とタグが重なる分析済みファイルを自動で見つけて注入します（明示的な fileIds がない場合のみ）。レスポンスでは、呼び出されたファイルIDが filesRecalled 配列に入ります。

チャットのリクエスト例

{
  "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 は、ファイルが自動で呼び出された場合にのみ含まれます（空の場合は省略）。

料金と課金

• アップロードと抽出：無料（テキスト抽出にトークンは課金されません）
• AI分析（analyze=true）：境界の検出＋セクションごとの要約＋全体の要約に実際に使われたトークンが、分析モデルの単価で課金されます。30,000文字以下は同期、30,000文字超は非同期で処理されます（status：analyzing）
• チャットへの注入：ドキュメントのテキストは入力トークンとしてカウントされ、通常のチャットリクエストと同様に課金されます
• ログ：コンソールの使用ログに file_upload（無料）と file_analyze（有料、実トークン）として表示されます

機能のオン・オフ

ドキュメント処理はパートナーアカウント単位で有効・無効を切り替えられます。コンソールの「機能設定」で管理し、オフの場合はすべてのファイルリクエストが403を返します。

• アカウント全体で無効：403 { code: 'FEATURE_DISABLED', feature: 'files' } を返します
• リクエスト単位：fileIds なし = ドキュメントを注入しません（通常どおり処理）

分析ステータスとチャンク

GET /api/v1/partners/v1/files/:id のレスポンスには analysisStatus、extractedText、chunks が含まれます。chunks は、分析が完了し totalChunks が2以上の場合にのみ配列になり（各チャンク：chunkIndex、context（要約）、最大10個のタグ）、それ以外は null です。アップロードのレスポンスには chunks はありません。

注意事項

• 形式のチェック：非対応の形式は 400 { code: 'INVALID_FILE_TYPE' } を返します
• その他のエラー：ファイルなし 400 FILE_NOT_PROVIDED / 10MB超 400 FILE_TOO_LARGE / 未知のファイル 404 FILE_NOT_FOUND / :id がUUIDでない場合は 400
• 分析に必要なもの：endUserId なしで analyze=true にすると 400 { code: 'END_USER_REQUIRED' } を返します
• 抽出の失敗：ドキュメントの抽出中にエラーが起きると 422 { code: 'EXTRACTION_FAILED' } を返します
• 残高チェック：分析リクエストの前にパートナーのクレジットを確認します。不足している場合は402を返します
• ナレッジベースへの自動取り込み：analyze=true の場合、各セクションの要約とタグが自動でナレッジベースに保存され、自動呼び出しの候補になります。endUserId を指定した場合は、そのユーザーのメモリー層にも追加されます。
• 再アップロード = 新しいファイル：アップロードのたびに新しいファイル（新しいid）が作成され、analyze=true の場合は再度分析・課金されます。ドキュメントは一度だけアップロードし、返されたidを fileIds で再利用してください。

エラーコード

共通エラー（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イベントのdataに含まれます。

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]

コスト

• 追加料金なし：感情分析は要約サイクルのプロンプト内で実行され、要約と感情サイクルのトークンはパートナーに課金されません。支払うのはチャットのターン自体の入力・出力トークンのみです。

注意事項

• 最初のサイクルの前：最初の要約サイクルが実行されるまで、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
  }
}

注意事項

• 固定料金：画像の生成は1回ごとに₩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

GPT-ImageとNano Bananaのモデルを、1つのキーでOpenAI Images APIと同じ形式で呼び出せます。モデル・解像度・品質ごとに1枚あたりの固定料金があり、表の金額がそのまま差し引かれます（生成枚数 × 1枚あたりの料金）。プロンプトの入力トークンのコストは1枚あたりの料金に含まれ、別途加算されません。

リクエストパラメータ

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）。

1枚あたりの料金（₩、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 = 1枚あたりの料金 × 実際に生成された枚数。アップストリームが画像を1枚も返さなかった場合は課金されません。
• GPT-Imageのレスポンスの usage（トークン数）は参考用で、料金計算には使われません。

エラーコード

共通エラー（401、400 本文の検証、402、429、503 など）のほかに、このAPIが返すコード：

エラーレスポンスは、他のAPIと同じ {"success": false, ...} 形式です（アンラップされるのは成功レスポンスのみです）。

時間のかかる生成 — 非同期レスポンス（202、任意）

高解像度や複数枚のリクエストは1分以上かかることがあります。リクエストヘッダー Prefer: respond-async を付けると、60秒以内に結果が出ない場合は接続を保持せず、ジョブIDとともに 202 Accepted が返り、サーバー上で最大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 秒ごとにポーリングしてください。ポーリングは無料で、1日のリクエスト上限にはカウントされません。APIキーごとに2秒に1回までに制限されており、それより頻繁にポーリングすると Retry-After（秒）付きで 429 IMAGE_JOB_POLL_RATE_LIMITED が返ります。レスポンスはHTTP 200で、状態は本文の status で示されます。

• 課金：結果が出た時点で1回だけ差し引かれます。待機中は見込み額が残高から確保され、失敗またはタイムアウトの場合は確保が解除されて課金されません。何度ポーリングしても再度課金されることはありません。
• 保持期間：結果とエラーはジョブ作成から24時間取得でき、その後は削除されます（以降は404）。画像が b64_json の場合、ポーリングのレスポンスも同じくらい大きくなります（画像1枚あたり数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 フィールドには、三災（3年続く災いの周期）、神殺（象徴的な星）、空亡、根の強さ、季節の強さ、大運・年運のタイムライン、四柱推命MBTIも入ります（追加料金なし。計算に失敗した場合は null）。

万歳暦（韓国の四柱推命の暦）による命式を計算します。四柱（年・月・日・時）それぞれについて、天干と地支、漢字、五行、通変星、蔵干、納音、十二運星、神殺を求めます。節気に基づく精密な計算で、四柱推命のリーディングを一通りお届けします — 命式分析（用神（喜ぶ五行）、扶抑、調候用神、日干の強弱、清濁、通関、病薬、五行の変数）→ 10の大運（現在の大運を含み、干支の合・沖・刑・害つき）→ 5年分の年運（歳運）（年ごとの等級・関係・解釈）→ 格局と詳細解釈 → 十干論、季節の状態、空亡、虚字、飛合、暗禄 — を、トップレベルの基本フィールド30個とオプションフィールド（サブフィールドを含めて200以上）で返します。出生時刻が不明な場合、null になるのは時柱（wonkuk.hour）と、実際の時刻が必要な trueSolarTime だけです。用神・格局・日干の強弱などの分析フィールドは、年・月・日の三柱（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枚）から重複なくカードを引きます。カードごとに正位置／逆位置、キーワード、意味、カード画像のURLが返ります。AIによる解釈はなく、意味はそのカードに決まった固定テキストです。そのため、使い方は3通りあります。

• タロットだけでアプリを作る — レスポンスのカード名・意味・画像をそのまま画面に描画します。
• タロット＋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（言語に依存しないカードID）・name（リクエストした言語）・nameEn・arcana（major | wands | cups | swords | pentacles）・reversed・keywords・meaning（引いた向きのもの）・imageUrl。
• spread：countで引いた場合はnullです。
• カード画像：imageUrl・cardBackUrlはWebP（横幅600px）で、URLにバージョン（v2）が入っているため変わりません — 取得してキャッシュし、再利用できます。逆位置のカードは画像を180度回転して表示してください（画像はカードごとに正位置の1枚だけです）。
• 画像の出典：1909年のライダー・ウェイト版オリジナルデッキのスキャン（パメラ・コールマン・スミス、パブリックドメイン）。78枚すべてと裏面は、ウィキメディア・コモンズにある1909年オリジナルデッキのスキャンです。ファイルごとの出典とライセンスは出典台帳にあります。旧URL（v1）も同じ画像を返すため、保存済みのURLを変更する必要はありません。
• costPoints：この呼び出しで差し引かれた金額（₩）。

料金

• 1回あたり定額 — 1枚でも10枚でも同じです。価格は料金の計算API表にあります。成功した呼び出しのみ課金され、同じ入力で繰り返し呼び出すとそれぞれ課金されます（冪等性）。
• 入力エラー（400）と残高不足（402）は課金されません。利用ログのエンドポイントはtarotです。
• 公開前に呼び出すと404 tarot_not_enabledを返します（課金なし）。

ウェイトの原典テキスト kb

公開されると、レスポンスにkbが追加されます。引いたカードごとに、A. E. ウェイト『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[]（ウェイトが挙げた別の説明はalternative、第3部§4の追加の意味はadditional）があります。
• statusはKBの表記をそのまま使います（verified＝原文の引用あり）。ウェイトが意味を挙げていない箇所（カップの2の逆位置）はruleId: null、status: "disputed"です。
• method: "celtic-cross"：ウェイトが同書で説明しているケルト式の占い方（10枚）。count・spreadの代わりに送ります。10個の各ポジションに対するウェイトの意味がpositionRuleに入ります。その他のspreadはウェイトの原文にない配置のため、ポジションの出典はありません（kb.method: null）。
• kb.caveats：意味はポジションによって変わるというウェイトの注記と、利用上の原則（占いのための道具であり、健康・法律・金銭の判断に代わるものではありません）。
• 公開前にmethodを送ると404 tarot_kb_not_enabledを返します（課金なし）。

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

エラーコード

共通エラー（401、400 本文の検証、402、429、503 など）に加えて、このAPIが返すコード：

count・spread・methodはちょうど1つだけ送ります。2つ以上、またはどれもない場合は共通の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でした）。他のエンドポイントと同じルールです。birthTimeなし、または精度を明示した呼び出しは以前と同じ結果になります。

エラーコード

共通エラー（401、400 本文の検証、402、429、503 など）に加えて、このAPIが返すコード：

西洋占星術トータルAPI

万歳暦と同じように、西洋占星術の計算をすべて1回の呼び出しで返します。デフォルトはネイタルチャート全体（太陽から冥王星までの10天体・月のノード・4つの感受点・ハウス（デフォルトはプラシーダス）・アスペクト・品位）です。リクエストにブロックを加えると、トランジット＋セカンダリー・プログレッション（timing）と2人のシナストリー（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°を超える）ではプラシーダスが定義できない場合があるため、代わりにポルフィリーで計算し、houses.porphyry.fallbackFrom = "placidus"で示します（黙って切り替えることはありません）。判定には出生地の緯度を使うため、同じ出生地なら時刻に関係なく常に同じ方式になります。housesExcludedには、計算できなかったその他の方式が理由とともに入ります（エラーレスポンスではありません）。
• aspects[]：orb＝正確な角度からのずれ（度）、strength＝exact（2°以内）・close（上限の半分以内）・wide、applying＝正確な角度に近づいていればtrue（不明ならnull）、outOfSign＝サインの境界をまたぐアスペクト（1段階弱く読みます）。
• moonSignUncertain：時刻が不明な場合、その日のうちに月がサインを移るならtrue — このときfeaturesの月のplanet_signに"uncertain": trueが付きます。
• readings（常に含まれ、追加料金なし）：HRUMが作成済みのリーディング文章。dignities[]＝品位（太陽から土星まで、天体ごとに最も強い状態1つ）、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ハウス、またはアセンダントから6°以内の12ハウスにある） — この5種類は+systemが付き、出生時刻と座標がある場合のみ出ます・planet_solar Ve_cazimi（太陽から17′以内）／Me_combust（17′~8°30′、太陽と同じサイン）／Ma_beams（それ以外で17°以内） — 3段階は重なりません・moon_phase waxing・waning・meta time_known（時刻あり — exact・approximate）／time_hour_level（approximateの場合に追加）／time_unknown。アスペクト系のキー（aspect・transit・progressed・syn_aspect）にはorb（正確な角度からのずれ（度）、小数点以下2桁）と、アスペクトがサインの境界をまたぐ場合のみ"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惑星。ネイタルのハウスはデフォルトの方式（プラシーダス。極地ではポルフィリー＋"fallbackFrom": "placidus"）を使い、キーには"system"が付きます — 別のhouseSystemsを送っても、この2つのキーはデフォルトの方式を使います。出生時刻または座標がない場合は出ません。
• プログレス→ネイタルのアスペクトは、ネイタルの惑星のみが対象です。キー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天体（＋アセンダント、MC）×相手の10天体（＋アセンダント、MC）のすべての組み合わせを調べます（向きを区別するため、aSu_bMoとaMo_bSuは別のキーです）。
• アセンダント（Asc）とミッドヘブン（MC）は、その人の出生時刻と座標が両方ある場合のみ計算されます（本人と同じルール。相手についてはsynastry.partner.angles/anglesOmittedを参照）。感受点が関わるクロスアスペクトはコンジャンクションとオポジションのみ、6°で調べます。唯一の例外はアセンダント同士のコンジャンクション（aAsc_bAsc_cj）で、17°まで認めます（プトレマイオス『テトラビブロス』 — 2人のアセンダントが17°以内なら強い結びつき、ルール[orb=17]）。実際の離角はorbに入ります。感受点は、その感受点を持つ人の時刻がわかっていれば計算されます。ディセンダントとICはアセンダントとMCのちょうど反対なので、別のキーはありません。
• astro_syn：古典的な6つの組み合わせ（太陽–月、金星–火星、月–金星、太陽–金星、月–火星、金星–土星）のうち、最も強いサインの関係2つ。両方向は1つのキーにまとめます（Su_Mo_se＝一方の太陽ともう一方の月が同じエレメント）。syn_sign：本人のすべてのポイント×相手のすべてのポイントのサインの関係（aAsc_bAsc_ss）。2人とも出生時刻がexactなら、パート・オブ・フォーチュン（PoF、昼夜で計算式を反転）もポイントとして含まれます（aPoF_bPoF_ss） — パート・オブ・フォーチュンはアセンダントとともに約4分で1°動くため、時単位（approximate）や不明な時刻では出しません。関係のコード：ss（同じサイン）・op（反対のサイン）・se（同じエレメント）・es（支え合うエレメント）・sm（同じクオリティ）・ef（エレメントの摩擦）・nt（無関係）。
• オーブ表とマイナーアスペクトの設定は、ネイタルチャートと同じorbs・minorAspectsを使います。2つのネイタルチャートの間には接近・分離がないため、applyingは常にnullです。
• どちらかの出生時刻が不明な場合、その人のチャートは正午で設定されます。その人の月が関わるアスペクトにはfeaturesで"uncertain": trueが付きます（月は1日に約13°動き、オーブより大きいため）。相手の感受点と組むアスペクト（aAsc_bMo_…、逆方向のaMo_bAsc_…）も同様です。
• 相手のハウスは計算しません（シナストリーのハウスオーバーレイは提供していません）。

デフォルトと選ぶ必要がある値

• ハウス方式（デフォルトplacidus）：1819年と1929年の辞典が「一般に使われている」と説明している方式です。極地ではポルフィリーに置き換え、fallbackFromで示します。別の方式が必要ならhouseSystemsで選んでください。
• プログレッションの1年の長さ（デフォルトtropical、365.24219日）：原典の「誕生日から次の誕生日まで」の1年です。ユリウス年（julian）との差は、80歳でプログレスの時刻にして約2.5分です。
• トランジットとプログレッションのオーブ（timing.orbDegrees、timingを送る場合は必須）：資料によって異なります（正確な角度の前8°から10°までの幅）。空のままにすると400を返します。
• 冥王星・ノード・感受点が関わるネイタルのアスペクトはデフォルトのオーブ表にありません：Leo（1928）とHeindel（1919）のオーブ表が扱っていないポイントです（冥王星の発見は1930年）。そのため、これらのポイントはネイタルのaspectsには出ません（位置とハウスには出ます）。シナストリーで感受点のクロスアスペクトだけを、コンジャンクション／オポジション6°で調べます（アセンダント同士のコンジャンクションのみ17°）。

提供していないもの

• マイナーな品位（トリプリシティ・ターム・フェイス）、レセプション、ネイタルのパート・オブ・フォーチュン（シナストリーのsyn_signでのみ使用）、天王星・海王星・冥王星の品位、パラレルとミッドポイント
• プログレスの感受点（プログレスのASC・MC） — 原典に方法が定義されていません
• DSC・ICの値は返しますが、featuresのキーは出しません（サウスノードはSnキーで出ます）
• 新月・満月・上弦・下弦の月相キー（moon_phaseはwaxing・waningのみ）、太陽に対するオリエンタル／オクシデンタル、プログレスの感受点のキー
• シナストリーのハウスオーバーレイ

料金

• 1回₩50、万歳暦と同じ — timing・partnerブロック、ハウス方式、マイナーアスペクトを加えても変わらず、課金は₩50の1回です。レスポンスのcostPointsは差し引かれた金額（₩）です。利用ログのエンドポイントはastrologyです。
• 計算が成功した場合のみ差し引かれます。入力エラー（400）と残高不足（402）は課金されません。
• 公開前に呼び出すと404 astrology_not_enabledを返します（課金なし）。

エラーコード

共通エラー（401、400 本文の検証、402、429、503 など）に加えて、このAPIが返すコード：

運勢フローAPI

1人の四柱推命から、大運・年運（歳運）・月運が命式にどう重なるかを計算し、グラフ用の数値と関係の一覧を返します。1回の呼び出しで1人、LLMは使いません。縦軸の値は「運の文字を加えた日干側のスコア」です — 命式の強弱の合計スコアに、運の文字ごとに命式と同じ文字別の表（生扶・剋洩・蔵干・通根）で採点した分を加え、±100で切り詰めます。運の良し悪しを測るものではありません（R-SAJU-UN-034）。身強・中和・身弱（日干の強弱）のラベルは命式のもので、運によって付け直されることはありません。

料金：1回₩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: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：大運または年運の文字が、命式と合わせて3文字の三合や方合を完成させる場合（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：大運数（最初の大運の年齢）。出生日（韓国の日付）の00:00から節入りまでの日数を、出生の時・分を入れずに数え、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は差し引かれた金額（₩）で、利用ログのエンドポイントはsaju-flowです。

エラーコード

共通エラー（401、400 本文の検証、402、429、503 など）に加えて、このAPIが返すコード：

相性API

2人の四柱推命から相性を計算します。1回の呼び出しで、四柱推命の相性（60×60の日柱相性表・目的別のスコアと6軸・天干／地支の関係・八字全体の五行バランス・通変星・相互の神殺（象徴的な星））、親密度の記号表（参考文献（1995）の男女日柱表による記号と等級）、星座の相性（太陽・月・アセンダントの3層に目的別の天体を加えたもの、星座相性の文章は最大2つ）、干支（生まれ年の動物）の相性（2人の生まれ年の動物の地支の関係と等級）を返し、さらに5つのスコアを目的別の重みで合わせた総合スコア（headerBreakdown）も返します。2026-10-16からは、2人の命式の間の合・沖・刑・害・破を位置ごとにまとめた関係表（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

2人の四柱推命をもとに相性を分析します。

リクエストパラメータ

details・flow・MBTIのオプションは追加料金なしです（1回あたり₩20のまま）。

• 時刻の補正：各人の四柱推命（日柱・八字スコア・総合スコア・親密度の記号表・干支・権威の分析・yearFlow・関係の文章）は1回だけ計算し、すべての項目で共有します。座標、personXCountry、精度exactのいずれも送らない場合は、入力した時刻をそのまま使います（万歳暦APIと同じ）。INTAアプリ（韓国、時刻を直接入力）と同じ相性が必要な場合は、2人ともpersonXCountry: "KR"（＋personXBirthTimePrecision: "exact"）を送ってください — 下の推奨の呼び出しを参照してください。出生時刻のない人は補正しません。デフォルト（送らなければ補正なし）は変わりません。
• 2026-10-11の変更：座標を送ると、四柱推命にも真太陽時の補正がかかるようになりました（以前は星座の相性にだけ使っていました）。この変更で1つのレスポンス内で四柱推命と星座が同じ時刻基準を使うようになったため、すでに座標を送っていた呼び出しでは四柱推命のスコアや日柱が変わることがあります。新しいフィールドと座標なしの呼び出しのレスポンスは変わりません。
• 日柱はコード値です：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）はこの例から省いています — 下のオプションの例を参照してください。この2人の場合、推奨の呼び出し（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軸グラフと同じ値です — 2人の日柱の組の相性表にある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から）：2人の命式の間の関係の一覧です。同じ位置（年・月・日・時 — 時柱は2人とも出生時刻がある場合のみ）の地支の組、2人の日干の間の干合と干沖、年柱の納音五行、そして2つの命式を合わせたときにだけ成立する三合と方合を調べます。各項目にはpositions（[A side, B side] — 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は2つの平均（例：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人のチャートの間で特に目立つ接点（太陽–月、金星–火星など）について、最大2つの作成済みリーディング文章。なければ空配列。各文章のlangは、テキストが実際に書かれている言語です（リクエストした言語のテキストがなければko）
• headerBreakdown：5つのスコア — 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を他の4軸に従来の比率で配分しました（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（課金なし）。ユーザーが日付欄に2桁の年を入力すると例えば0090として入るため、画面側でも防いでください。相性表に結果が見つからない場合は400 COMPAT_UNAVAILABLE（課金なし）
• tti.tier：参考文献（1995）の干支の相性による等級の文字列（例：대길・길・중길・보통・주의・흉 — 大吉から凶まで）。tti.relation.type＝2つの動物の地支の関係 — 충（沖）・원진（怨嗔）・형（刑）・해（害）・육합（六合）・반합（半合）・파（破）のいずれか（複数重なる場合はこの順で最初のもの）、なければnull。detailは半合のときだけ（例：수국(水局)）。tti.relation.relations＝重なっているすべての関係（同じ順、例：丑・未 ["충","형"]、なければ空配列）
• ttiには動物・関係・等級だけが入ります。参考文献の干支相性の文章は含まれません（2026-10-11から）。
• categoryNarrative：この関係（purpose）での2人の様子を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です（例外は破の2組だけです）。新しい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 }, ... }
  }
}

注意事項

• 基本データ：2人の生年月日は必須です。時刻と性別は任意です。親密度の記号表は、性別がなくても同性でも返します（両方向を合わせたもの）。星座の相性のアセンダントには出生時刻が必要です。
• 得られるもの：星座の相性はトロピカル方式の黄道十二宮を使います。関係の文章は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の変更：相性の文章の韓国語の助詞が、直前のパッチム（終声）に合うようになりました（例：「임와」 → 「임과」、「병는」 → 「병은」）。キー、順序、数値、他の言語のテキストは変わりません。
• 料金：1回の呼び出しごとに₩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は、利用を申請したアカウントにだけ公開されています。それ以外のアカウントには3つのパスすべてで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}

ルールカード1枚とその原典を返します。無料です。

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

現在公開されている解釈KBの版を返します。無料です。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が変わったときに取得し直してください。

エラーコード

共通エラーに加えて：