API リファレンス

統合の基本

#ベース URL

すべてのエンドポイントは、このデプロイ自身のドメインの /v1 配下にあります。リージョンの選択はありません — 上流ベンダーへのルーティングはゲートウェイの内部で行われます。

#認証ヘッダー

認証に必要なのは Authorization: Bearer ヘッダー 1 つだけです。署名もタイムスタンプもユーザー単位のヘッダーも不要です — 他のゲートウェイが Bearer トークン以外に要求するものは、ここには一切ありません。

#エラー形式

ゲートウェイ側の拒否には、type が "xiaoxiang_error" の OpenAI 形式のエラー形式を使います。上流のエラーはそのまま転送され、非同期タスクのエンドポイントはフラットなボディで応答し、2 つのケースではボディがまったくありません — パーサーを書く前にエラーのページを読んでください。

error.json

HTTP/1.1 402 Payment Required
X-Oneapi-Request-Id: 2026091023...

{
  "error": {
    "message": "insufficient account balance, please top up to continue (request id: 2026091023...)",
    "type": "xiaoxiang_error",
    "code": "insufficient_user_quota"
  }
}

5 つのエラー形式とエラーコード一覧 →

#再試行ポリシー

429 と 5xx は指数バックオフで再試行し、Retry-After があればそれに従ってください。4xx の検証エラーは再試行しないでください — 同じボディでは再び失敗します。課金対象の送信には Idempotency-Key を付けてください。タイムアウト後の再試行で 2 つ目のジョブを開始せず、最初の結果がリプレイされます。

backoff.py

import time, requests

def call_with_backoff(url, headers, body, tries=5):
    for i in range(tries):
        r = requests.post(url, headers=headers, json=body)
        if r.status_code not in (429, 500, 502, 503, 504):
            return r
        # 429 and 413 have no JSON body — never parse before checking status.
        wait = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait)
    r.raise_for_status()

冪等キーの仕組み →

#機械可読な仕様

同じ仕様を 2 つの形式で生成しています：クライアント生成や Postman などの API ツール向けの OpenAPI と、コーディングエージェントに貼り付けられる単一の Markdown ファイルです。どちらもこれらのページから再生成されるため、今読んでいる内容とずれることはありません。

openapi.json

OpenAPI 3.1 — ドキュメントに記載されたすべてのパス、そのパラメーターとエラーレスポンス。

llms-full.txt

ワイヤー仕様全体を 1 つの Markdown ファイルにまとめたもの。エージェントのコンテキストウィンドウに収まるサイズです。

llms.txt

全ドキュメントページの簡潔なインデックス。最初にこれを取得する AI クライアント向けです。

サーバー URL はこのドメインに書き換えられるため、生成したクライアントに追加の設定は不要です。

generate-a-client.sh

# Any OpenAPI generator works; this is the common one.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.aisplice.store/openapi.json \
  -g python \
  -o ./gateway-client

#エンドポイント一覧

すべてのパスは OpenAI のリクエストボディを受け付けます — ベンダー固有のパラメーター（anthropic tool_use、gemini thinking_config）はそのまま転送されます。ベンダーネイティブのルートと凍結された旧ルートは、互換性のページに別途記載しています。

テキスト
POST	/v1/chat/completions	マルチターンチャット、ツール呼び出し、ストリーミング、JSON モード。
POST	/v1/responses	構造化出力と推論に対応した単発のテキスト生成。
POST	/v1/messages	Anthropic ネイティブの形式 — 認証は同じで、アダプターは不要です。
POST	/v1/responses/compact	コンパクションに対応したモデルで長い会話を圧縮します — ストリーミング形式はありません。
ベクトル
POST	/v1/moderations	同じワイヤーフォーマットでのコンテンツモデレーション。
音楽
POST	/v1/music/generations	非同期の音楽生成 — task_id を返します。Webhook も任意で利用できます。
GET	/v1/music/tasks/:task_id	非同期音楽タスクのステータスと進捗をポーリングします。
GET	/v1/music/tasks/:task_id/content	完成した音声をゲートウェイ経由で取得します。
画像
POST	/v1/images/tasks	非同期の画像生成。画像モデルが使用するルートです — task_id を返します。Webhook も任意で利用できます。
GET	/v1/images/tasks/:task_id	非同期画像タスクのステータスと進捗をポーリングします。
GET	/v1/images/tasks/:task_id/content	最終的な画像 URL を取得します — 永続リンクなので保存しても安全です。
動画
POST	/v1/videos	OpenAI 形式の動画生成（Sora、Doubao） — Webhook も任意で利用できます。
GET	/v1/videos/:task_id	非同期タスクのステータスをポーリングします。結果は /content にあります。
GET	/v1/videos/:task_id/content	完成した動画をゲートウェイ経由でダウンロードします。
DELETE	/v1/videos/:task_id	まだ終了状態に達していないタスクをキャンセルします。
POST	/v1/videos/:video_id/remix	対応モデルで、既存の動画を新しいプロンプトで再生成します。
3D
POST	/v1/model3d/tasks	非同期の 3D アセット生成と後処理 — task_id を返します。
GET	/v1/model3d/tasks/:task_id	3D タスクをポーリングします。結果の URL はタスクのボディに含まれ、/content ルートはありません。
メディア
POST	/v1/media/upload-policy	画像、動画、音声、一般ファイル向けに、設定された上限までの短期間有効なアップロードポリシーを作成します。
アプリ内サブスクリプション
POST	/v1/google-play/verify	このキーに設定されたサービスアカウントで、Google Play の購入トークンをアプリに照会します — 無料で、モデル呼び出しはありません。
POST	/v1/xsolla/verify	このキーに設定した Xsolla API キーで、Xsolla ユーザーに有効なサブスクリプションがあるか確認します。無料、モデル呼び出しなし。
アカウント
GET	/v1/balance	アカウント残高と、このキーであといくら使えるか — 無料で、モデル呼び出しはありません。
メタデータ
GET	/v1/models	このキーで利用できるすべてのモデルを一覧表示します。
GET	/v1/models/:model	1 つのモデル情報を取得します — Anthropic や OpenAI のクライアントが起動時に確認する形式です。

まだ解決しませんか？

リクエスト ID かエラーメッセージを送っていただければ、こちらで調査します。

前へファイルのアップロード次へ非同期タスク