模型回退

模型之间的自动故障转移

models 参数可以在主模型的模型服务提供商宕机、触发速率限制，或因内容审核拒绝回复时，自动尝试其他模型。

工作原理

按优先级提供一个模型 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-latest', 'gryphe/mythomax-l2-13b'],
  messages: [
    {
      role: 'user',
      content: '人生的意义是什么？',
    },
  ],
});

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

回退行为

如果你所选的模型返回错误，OpenRouter 会尝试改用回退模型。如果回退模型也宕机或返回错误，OpenRouter 会返回该错误。

默认情况下，任何错误都可能触发回退模型，包括：

• 上下文长度校验错误
• 过滤型模型的审核标记
• 速率限制
• 服务中断

定价

请求按最终实际使用的模型计费，该模型会在响应体的 model 字段中返回。

与 Anthropic Messages API 一起使用

Anthropic Messages API 端点（/api/v1/messages）接受 fallbacks 参数，形状与 Anthropic SDK 所用的一致。每一项指定一个按顺序尝试的回退模型，该列表会映射到 OpenRouter 的 models 路由，因此回退会在上文列出的同类错误（速率限制、服务中断、审核拒绝）时触发，而不仅仅是在拒绝时触发。

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  baseURL: 'https://openrouter.ai/api',
  apiKey: '<OPENROUTER_API_KEY>',
});

const message = await anthropic.beta.messages.create({
  model: 'anthropic/claude-sonnet-4.5',
  max_tokens: 1024,
  fallbacks: [{ model: 'anthropic/claude-opus-4.1' }],
  messages: [{ role: 'user', content: '人生的意义是什么？' }],
});

限制

• 每个 fallbacks 条目只接受 model 字段。每次尝试的覆盖项（如 max_tokens、thinking、speed 或 output_config）会被拒绝，并返回 400 错误。
• fallbacks 不能与 models 参数同时使用；同时发送两者会返回 400 错误。
• fallbacks 最多接受 3 个条目；更长的列表会返回 400 错误。

与 OpenAI SDK 一起使用

要在 OpenAI SDK 中使用 models 数组，请把它放在 extra_body 参数中。在下面的示例中，会先尝试 ~openai/gpt-latest，然后按顺序将 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-latest",
    extra_body={
        "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
    },
    messages=[
        {
            "role": "user",
            "content": "人生的意义是什么？"
        }
    ]
)

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