Skip to Content
ガイドルーティングルーティング

ルーティング

ルーティング：リクエストを、APIキーまたはルールで許可したモデルへ送る仕組みです。 モデルを明示する方法と、auto で候補から選ぶ方法があります。

方法を選ぶ

方法向いている用途model の値
モデルを明示する応答特性やモデルを固定したいGET /v1/models が返したモデルID
自動選択設定した複数の候補を順番に評価したいauto
最安値を優先する自動選択候補のうち、入出力単価の合計が低いモデルから試したいauto

利用できるモデルは、APIキーごとに確認します。

Shell
curl "$AI_GATEWAY_BASE_URL/v1/models" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"

モデルを明示する

取得したモデルIDを model に指定します。

Shell
curl -i "$AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<GET /v1/modelsが返したモデルID>",
    "messages": [
      { "role": "user", "content": "こんにちは。" }
    ]
  }'

一覧にない公開モデル名やプロバイダー名を組み合わせて、新しいモデルIDを作ることはできません。

自動選択を使う

APIキーまたはルールで自動選択候補を設定し、リクエストに model: "auto" を指定します。 候補が未設定の場合は、利用可能なモデルが価格順に評価されます。

Shell
curl -i "$AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "こんにちは。" }
    ]
  }'

「最安値を優先」を有効にすると、設定した候補を入出力単価の合計が低い順に評価します。 価格を取得できない候補は、価格を取得できる候補のあとに評価されます。

結果を確認する

成功したレスポンスでは、実際に応答したモデルを本文の model と次のヘッダーで確認できます。

HTTP
X-AIGateway-Requested-Model: auto
X-AIGateway-Served-Model: claude-sonnet-4-6
X-AIGateway-Fallback-Count: 0

設定できること

  • モデルを明示する：GET /v1/models が返したモデルIDを model に指定する
  • 公開モデル名を使う：一覧にない文字列をモデルIDへ加えない
  • 自動選択：model: "auto" を指定し、自動選択候補から選ぶ
  • 最安値を優先：自動選択候補を価格順に評価する
  • フォールバック：最初の候補が応答できない場合に、設定した別モデルを順番に試す
  • 自動選択を必須にする：個別モデルIDの指定を禁止し、auto だけを利用可能にする

モデルの許可状態、BYOKの有無、プロバイダーの状態などにより、同じ設定でも利用可能な候補は変わります。 固定したモデル一覧をアプリケーションへ埋め込まず、必要に応じて /v1/models を読み直してください。

プロバイダー、プロバイダーのAPIキー、フォールバック、再試行をリクエストボディで上書きすることはできません。 これらはダッシュボードのAPIキーまたはルールで設定します。

GET /v1/models が返す一覧の形、auto の扱い、使えないモデルを指定したときのエラーは、APIリファレンスの「モデル一覧」にまとめています。

モデルフォールバック