開発者向けはじめにガイド

HRUM 四柱推命（サジュ）APIをはじめて組み込むときの順番です。登録、最初の呼び出し、課金、エラー処理をすべてこのページにまとめています。エンドポイントごとのパラメータの全体は APIドキュメントにあります。

登録する前に結果を見てみたいですか？ プレイグラウンド ならキーなしで、月5回まで無料で試せます。

AIにアプリを作らせる — 無料の電子書籍（韓国語）

電子書籍を選ぶ（韓国語）オールインワン占いアプリ（韓国語）キャラクターチャットアプリ（韓国語）会員制Webアプリ（韓国語）

1. コンソールに登録

  1. コンソールのログイン画面で 新規登録 タブを選び、メールアドレスとパスワードを入力します。
  2. 受信トレイの認証メールを開いて認証ボタンを押し、もう一度ログインします。
  3. 新しいアカウントには無料クレジット ₩1,000 が付与されます（登録が不正利用対策の検知に引っかかった場合、付与が保留されることがあります）。

2. APIキーを発行

  1. コンソールの APIキー 画面でキーの名前（例：「本番サーバー」）を入力し、 発行を押します。
  2. 新しいキーは 発行直後に一度だけ表示されます。すぐにコピーして、サーバーの環境変数など安全な場所に保管してください。なくした場合は新しく発行してください。
  3. キーはサーバーでだけ使ってください。ブラウザやアプリのコードに入れると、誰でも取り出して使えてしまいます。

同じ画面の リクエスト制限 で、1秒あたりと1日あたりのリクエスト上限を設定できます。キーが漏れたりコードがループしたりしたときに残高を守れます。

3. 最初の呼び出し — 万歳暦

すべてのリクエストは https://api.hrum.ai/api/v1/partners/v1/以下のパスに送り、キーは X-Partner-Api-Key ヘッダーに入れます。下は、生年月日時から命式を計算する万歳暦（マンセリョク）の呼び出しです。

curl

export HRUM_API_KEY="your-api-key"

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

Python (requests)

import os
import requests

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

Python 標準ライブラリ urllib の既定の User-Agent はセキュリティルールでブロックされ、 403が返ります。 requestsを使うか、 urllibを使う場合は User-Agent: <app-name>/<version> ヘッダーを自分で設定してください。

JavaScript（Node 18 以上、サーバー側）

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

4. レスポンスを読む

成功すると {"success": true, "data": { … }}が返ります。万歳暦の場合、 data には命式の四柱（年・月・日・時）(wonkuk)、五行のバランス (ohaengBalance)、用神（喜ぶ五行、 yongshin）、格局、大運、年運（歳運）などが入ります。フィールドの一覧は 万歳暦APIドキュメント をご覧ください。

万歳暦のような計算型APIは、同じ入力ならいつも同じ結果を返します。一度データベースに保存して再利用すれば費用はかかりません。

5. 課金とクレジット

商品ごとの単価は 料金 ページにあります。主な計算型APIの料金（現在の料金表より）:

6. エラー処理

エラーのボディは {"success": false, "statusCode": 400, "code": "…", "message": "…", "timestamp": "…"}の形です。 statusCode と codeで分岐し、message の文言には頼らないでください。

コード意味対処
400リクエストのパラメータが正しくないリクエストを直してください。同じリクエストをリトライしないでください。
401APIキーがない、または正しくないヘッダー名（X-Partner-Api-Key）とキーの値を確認してください。
402クレジットが足りません。 code は INSUFFICIENT_BALANCE、または残高の事前確認がないAPI（万歳暦など）ではなしチャージしてから、もう一度呼び出してください。
403セキュリティルールでブロック（ボディはJSONではなくHTML、error 1010）— 既定の User-Agent がブロックされている HTTP クライアント（Python urllib など）。APIキーの問題ではありませんUser-Agent: <app-name>/<version> ヘッダーを設定してください。キーを変えても解決しません。
404アカウントで有効になっていない機能（*_not_enabled）、または存在しないリソース課金されません。パスと機能が有効かを確認してください。
422処理できない入力（例： PROMPT_TOO_LONG)入力を短くするか直してください。
429レート制限の超過Retry-After ヘッダーが示す時間だけ待つか、ない場合は少し（最大1分）待ってからリトライしてください。
500 · 503 · 504サーバーエラー · 一時的に利用不可 · 上流のタイムアウト間隔を広げながら数回リトライしてください（例：1秒 → 2秒 → 4秒）。

サービスを守るため、すべてのAPIキーには常に1分あたり300リクエストの上限があります。詳しくは エラーコード と レート制限 のドキュメントをご覧ください。障害の状況は ステータスページ で確認できます。

次のステップ

お問い合わせ: contact@float.do · 運営: FLOAT Co., Ltd.