メインコンテンツへスキップ
OrcaRouter は 1 つが成功するまで順番に複数のモデルを試せます。可用性 (あるプロバイダがスロットルされていたり停止していたりするとき) と コスト管理 (安価なモデルを優先し、必要なら強力なモデルにフォール バック) に有用です。

​
使い方

extra_body.models にモデル ID の順序付きリストを置き、 extra_body.route を "fallback" に設定します。トップレベルの model フィールドは依然として意味を持ちます——最初の試行——が、 チェーンが存在する場合 OrcaRouter はそれを優先します。 
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "models": ["openai/gpt-4o", "anthropic/claude-haiku-4.5", "google/gemini-2.5-pro"],
        "route": "fallback",
    },
)

​
ルール

  • チェーンには最大 5 モデル。超過分は黙って切り詰められます。
  • 推奨: チェーン内のすべてのモデルは 同じエンドポイント種別 (すべて chat、またはすべて image) であるべきです。チャットモデルと 画像モデルを混在させてもゲートウェイはクラッシュしませんが、実際に リクエストを処理するフォールバックは呼び出したエンドポイントと 一致する必要があります (例: /v1/chat/completions を呼ぶ場合、 チェーン内のチャットモデルのみ使用可能)。
  • フォールバックの挙動:
    • 解決不能な orcarouter/{name} エントリ (誤名、無効化されたルーター) は黙ってスキップされます。
    • 呼び出すキーがアクセスできないモデル (モデル許可リスト不一致) は黙ってスキップされます。
    • 主モデルが上流で失敗したとき (5xx / 429 / ネットワークエラー)、 次のチェーンエントリが試されます。
    • リクエストが失敗するのは、チェーン全エントリを使い切ったとき のみです。
    • ストリーミングの注意: レスポンスの最初の 1 バイトでも クライアントに送信されると、フォールバックはもう発動できません ——上流がストリーム中に切断した場合、クライアントには切り詰め られたストリームが見えるだけで、次モデルへの透明な再試行は 起きません。
  • 課金はレスポンスを実際に処理したモデルのレートで行われます ——主モデルのレートではありません。
  • extra_body.route は厳密に "fallback" でなければチェーンは 発動しません。それ以外の値 (または欠如) はチェーンが無視され、 トップレベルの model のみが使われます。

​
どのモデルが処理したかを知る方法

X-Orca-Fallback-Level と X-Orca-Fallback-Model のレスポンス ヘッダを確認してください。レスポンスヘッダ を参照。 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" は level 0; それ以外はフォールバックモデル名

​
このパターンを使わない方が良いとき

OrcaRouter にチェーンを書かずに 自動で 最安の利用可能なモデルを 選ばせたい場合は、orcarouter/auto を 使ってください。フォールバックチェーンは、順序を明示的に制御したい ケースのためのものです。