命理 API 連携ガイド

易覧AI命理分析 API の接続方法、対応モデル、リクエスト仕様、課金ルール、呼び出し例

3月 25, 2026

本ページでは、易覧AI命理 API の標準的な連携方法を説明します。

現在のインターフェースは OpenAI 互換プロトコルに準拠しており、chat/completions と completions に対応したクライアントで利用できます。

1. 接続情報

接続先、リクエスト方式、標準エンドポイント

項目	説明
推奨ベース URL	`https://ylan.ai/api/openai`
互換ベース URL	`https://ylan.ai/api/openai/v1`
既定のリクエスト方式	`POST`
モデル一覧	`GET /models`
モデル詳細	`GET /models/{id}`
対話エンドポイント	`POST /chat/completions`
旧 completions 互換エンドポイント	`POST /completions`

クライアント側で /v1 を自動付与する実装では、https://ylan.ai/api/openai を優先して設定してください。

認証方式

すべてのリクエストで、以下のヘッダーを指定してください。

Authorization: Bearer sk-...

API Key はユーザーアカウントに紐づき、消費は当該アカウントの有料クレジットプールから差し引かれます。

Authorization を設定できない一部のサードパーティクライアント向けに、api-key: sk-... および x-api-key: sk-... も互換ヘッダーとして受け付けます。

マルチターン対話

マルチターン対話に対応しています。呼び出し側は messages 配列に履歴メッセージを含めることで、継続した文脈を維持できます。

2. 公開範囲とモデル

公開範囲

区分	説明
公開機能	命理分析 API のみ公開
汎用チャット	公開対象外
対応シナリオ	単人分析とペア分析に対応
出力基準	サイト内の命理体験と同一基準

利用可能モデル

利用可能なモデルは GET /models のリアルタイム結果が基準です。プラットフォームの能力更新に応じて変更される場合があります。

モデル	説明
`openai/gpt-5.4`	高品質な命理解釈に適したモデル
`openai/gpt-5.3-chat`	汎用的な命理解釈と継続対話に適したモデル
`deepseek/deepseek-v3.2`	多様な命理解釈と継続対話に適したモデル

3. リクエスト仕様

レスポンス形式

条件	返却形式
`stream=true`	OpenAI 互換の SSE ストリームを返却。データ形式は `chat.completion.chunk`、終了時は `data: [DONE]`
`stream=false`	標準的な `chat.completion` JSON を返却
`POST /completions`	OpenAI 互換の `text_completion` JSON または SSE ストリームを返却
非ストリーミング成功時のヘッダー	`x-ylan-charged-credits` と `x-ylan-remaining-paid-credits` を返却

リクエストパラメータ

パラメータ	型	説明
`model`	`string`	`GET /models` で返されるモデル名
`messages`	`array`	OpenAI 互換のメッセージ配列。少なくとも 1 件の `user` メッセージが必要
`prompt`	`string`	旧 `completions` 互換入力。`messages` 未指定時に単発テキストとして利用可能
`input`	`string`	一部サードパーティクライアント向け互換入力。`messages` 未指定時に利用可能
`stream`	`boolean`	ストリーミング応答を使うかどうか。既定値は `false`
`locale`	`string`	出力言語。例: `ja`、`zh`、`en`
`topic`	`string`	命理トピック。例: `wealth_pattern`、`marriage_status`
`subject_mode`	`string`	分析モード。`single` または `pair`
`method`	`string`	現在の命理パイプラインで解釈される分析方式
`birth_profile`	`object`	単人分析向けの出生情報入力
`chart_input`	`object`	外部で排盤済みの構造化入力
`pair_state`	`object`	ペア分析向けの入力
`metadata`	`object`	`topic`、`locale`、`birthProfile`、`pairState` などを補足する拡張メタデータ

単人分析のストリーミング例

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "locale": "ja",
    "topic": "wealth_pattern",
    "subject_mode": "single",
    "birth_profile": {
      "calendar": "solar",
      "birthDate": "1992-08-15",
      "birthTime": "09:30",
      "gender": "male",
      "location": "Shenzhen"
    },
    "messages": [
      {
        "role": "user",
        "content": "今年の金運の流れを分析してください。"
      }
    ]
  }'

双人合盤のストリーミング例

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek/deepseek-v3.2",
    "stream": true,
    "locale": "ja",
    "topic": "marriage_status",
    "subject_mode": "pair",
    "pair_state": {
      "subjects": [
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1992-08-15",
            "birthTime": "09:30",
            "gender": "male",
            "location": "Shenzhen"
          }
        },
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1995-03-08",
            "birthTime": "22:15",
            "gender": "female",
            "location": "Guangzhou"
          }
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "二人の相性と長期的な関係の方向性を分析してください。"
      }
    ]
  }'

4. 課金とエラー処理

課金ルールと課金確定タイミング

条件	ルール
単人命理分析	成功した応答ごとに 100 クレジット
双人合盤分析	成功した応答ごとに 200 クレジット
`need_input`	課金対象外
消費対象	有料クレジットのみ。登録特典や付与クレジットは対象外
`stream=true`	最初の有効な可視コンテンツが返った時点で課金確定
`stream=false`	応答が完全に成功して返った時点で課金確定
タイムアウト・失敗・空応答	課金は確定されないか、現行ルールに従って返還

主なエラーコード

HTTP ステータス	エラーコード	説明
`400`	`invalid_messages`	有効なメッセージがない、または `user` メッセージが不足
`400`	`invalid_prompt`	`messages`、`prompt`、`input` がすべて未指定
`400`	`invalid_model`	指定モデルが公開対象外
`401`	`invalid_api_key`	API Key が無効、または未指定
`402`	`insufficient_paid_credits`	有料クレジットが不足
`500`	`request_timeout`	リクエストがタイムアウト
`500`	`request_failed`	リクエストに失敗
`500`	`internal_error`	サーバー内部エラー
`502`	`empty_response`	モデルが有効な可視コンテンツを返さなかった

need_input 応答

出生情報、トピック情報、またはペア分析の情報が不足している場合、API は need_input 形式の補足応答を返すことがあります。これは分析に必要な条件を補完するための応答であり、課金対象ではありません。