模型兜底

主模型暂时不可用（529 过载 / 429 限流 / 5xx 故障 / 连不上）时，请求会自动换到备用模型继续，Agent 任务不会因为一次上游故障中断。用法与 OpenRouter 的 models 参数兼容。

有两种设置方式，任选其一：

场景	做法
Claude Code、Cursor 等改不了请求参数的客户端	在「API Keys」页给 Key 设置备用模型，不用改任何配置
自己写代码调用 API	请求体加 models 参数

方式一：在 API Keys 页设置备用模型

1. 打开 API Keys 页面。
2. 在要使用的 Key 那一行，从「备用模型」下拉框选一个模型，选完即自动保存。

之后用这个 Key 发出的请求，主模型不可用时都会自动换到这个备用模型。

方式二：请求体传 models

model 仍然是主模型，models 按顺序列出备用模型。不传 model 时，取 models 的第一个当主模型。

curl -X POST "https://router.bumo.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-5-5",
    "models": ["gpt-6-astra", "gemini-3.8-flash"],
    "messages": [{ "role": "user", "content": "你好" }]
  }'

• 请求优先：请求里带了 models 时以请求为准，忽略 Key 上设置的备用模型。
• 关闭本次兜底：传 "models": []，本次请求只用主模型，Key 上的备用模型也不会启用。
• 最多 3 个模型（含主模型），超出部分忽略；重复的模型自动去重。
• models 只给平台使用，不会转发给上游模型服务。

什么时候会换模型

• 只有主模型的所有线路都失败，且错误属于可重试的（429 / 529 / 5xx / 网络连接失败）时，才换下一个模型。
• 4xx 参数错误不兜底（如上下文超长、请求体格式错误），原样返回给你，换模型也解决不了。
• 流式输出开始后不再切换：切换只会发生在返回任何内容之前，不会出现前半段来自 A 模型、后半段来自 B 模型的拼接。
• 备用模型不存在或未开通时直接跳过。
• 链上所有模型都失败时，返回最后一个模型的错误。

计费与查看

• 按实际成功的模型计费，价格以该模型的定价为准，没有额外费用。
• 响应体里的 model 是实际处理请求的模型；发生兜底时，响应头会带 X-Router-Fallback-From: <主模型>，可以在代码里据此判断。
• 钱包 的「消费记录」中，兜底请求会在模型名下显示「兜底自 <主模型>」。