通过在请求中传入 models 数组，可以为主模型配置一组备用模型。当主模型的所有提供商宕机、限速或内容被过滤时，OpenRouter 自动切换到下一个模型。响应中的 model 字段会返回实际使用的模型，费用也按实际模型计费。

OpenRouter 模型 Fallback

工作原理

在请求中提供按优先级排列的模型 ID 数组。如果第一个模型所有提供商都返回错误，OpenRouter 自动尝试下一个。

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.6',  // 首选
    'gryphe/mythomax-l2-13b',       // 备用
  ],
  messages: [
    { role: 'user', content: 'What is the meaning of life?' },
  ],
});

console.log(completion.choices[0].message.content);

触发 Fallback 的条件

以下任一情况会触发切换到备用模型：

• 上下文长度超限
• 内容被审核拦截
• 提供商限速
• 提供商宕机

费用计算

按实际使用的模型计费，响应体的 model 字段会显示实际用到的模型。

与 OpenAI SDK 配合使用

通过 extra_body 参数传入 models 数组：

from openai import OpenAI

openai_client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="<OPENROUTER_API_KEY>",
)

completion = openai_client.chat.completions.create(
    model="openai/gpt-4o",  # 第一个尝试的模型
    extra_body={
        "models": [         # fallback 列表（按顺序尝试）
            "anthropic/claude-sonnet-4.6",
            "gryphe/mythomax-l2-13b",
        ],
    },
    messages=[
        {"role": "user", "content": "What is the meaning of life?"}
    ]
)

print(completion.choices[0].message.content)

跨模型性能优化

配合 provider.sort 的 partition: "none" 选项，可以跨多个模型按性能全局排序，自动选择当前最优：

const completion = await openRouter.chat.send({
  models: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5-mini',
    'google/gemini-3-flash-preview',
  ],
  messages: [{ role: 'user', content: 'Hello' }],
  provider: {
    sort: {
      by: 'throughput',
      partition: 'none', // 跨所有模型全局排序，不再按模型分组
    },
  },
});

默认情况下（partition: "model"），首选模型的提供商始终优先。设置 partition: "none" 后，所有模型的所有端点统一排序，哪个当前性能最好就用哪个。

---

常见问题

Q: 如果 fallback 模型也失败了怎么办？

A: OpenRouter 会返回最后一个模型的错误信息。建议选择多个可靠性不同的备用模型，例如主模型用高性能模型，备用模型用开源模型。

Q: models 数组中的模型可以来自不同的厂商吗？

A: 完全可以。OpenRouter 统一了接口，混合使用 Anthropic、OpenAI、Google 等不同厂商的模型是主要使用场景之一。

Q: 如何知道某次请求实际用了哪个模型？

A: 查看响应体的 model 字段，它会显示实际路由到的模型 ID。