跳转到主要内容
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。回退链适用于 那些你需要显式控制顺序的场景。