跳轉到主要內容
OrcaRouter 能按順序嘗試多個模型直到有一個成功。常用于提升可用性 （某家服務商被限流或宕機時）和成本控制（優先調用便宜模型，必要時 回退到更強的模型）。

​
如何使用

在 extra_body.models 中放一個有序的模型 ID 列表，并把 extra_body.route 設為 "fallback"。頂層的 model 字段仍然有意義 ——它是第一次嘗試——不過當 models 鏈存在時，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）。把一個 chat 模型混進 image 模型不會讓網關崩潰，但實際承接請求的回退條目 必須匹配你調用的端點（例如，調用 /v1/chat/completions 時，鏈中 只有 chat 模型可用）。
  • 回退行為：
    • 無法解析的 orcarouter/{name} 條目（錯誤的名字、被禁用的路由器） 會被靜默跳過。
    • 調用密鑰無權訪問的模型（模型白名單不匹配）會被靜默跳過。
    • 當主模型在上游失敗（5xx / 429 / 網絡錯誤）時，會嘗試鏈中的下一條。
    • 只有當鏈中的每一條都耗盡，請求才會失敗。
    • 流式警示：一旦響應已經發出任何一個字節給客戶端，回退就不能 再啟動——如果上游中途掉線，客戶端看到的是被截斷的流，而不是 透明切換到下一個模型。
  • 計費按實際承接響應的那個模型的費率計算——不是按主模型。
  • 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。回退鏈適用于 那些你需要顯式控制順序的場景。