OpenRouter 兼容

BigModel.io 在 /v1/chat/completions、/v1/messages 和 /v1/responses 上支持 OpenRouter 的主要请求约定。本页是精确的规则说明；如需逐步迁移，请看从 OpenRouter 迁移。

#模型名称如何解析

不含 / 或 : 的普通名称（如 glm-5.3）按原样使用。其他名称会先检查 Key 的分组是否明确提供该名称，然后按顺序尝试以下变体，使用第一个可用的：

1. 完整名称：z-ai/glm-5.3:nitro
2. 去掉路由后缀：z-ai/glm-5.3
3. 再去掉 provider/ 前缀：glm-5.3
4. 第 2 步的点号换成短横线：z-ai/glm-5-3
5. 第 3 步的点号换成短横线：glm-5-3

细节：

• 只去掉 :nitro、:floor、:exacto，不区分大小写。:free 请求永远不会由付费模型处理。
• 只去掉一层 provider/ 前缀，含两个斜杠的名称保留前缀。
• 「提供」指分组列出了该模型或为它配置了价格。
• 全部不匹配时，按原名称继续转发，返回普通的未知模型错误：503 api_error「No available accounts」。见模型 ID。

#用 models 数组做备选

models 是 model 失败时依次尝试的模型列表。

curl https://bigmodel.io/v1/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "models": ["glm-5.3", "deepseek-v4-pro"],
    "messages": [{"role": "user", "content": "总结一下这段 diff。"}]
  }'

import os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "总结一下这段 diff。"}],
    extra_body={"models": ["glm-5.3", "deepseek-v4-pro"]},
)
print(completion.model, completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://bigmodel.io/v1", apiKey: process.env.BIGMODEL_API_KEY });

const completion = await client.chat.completions.create({
  model: "kimi-k3",
  models: ["glm-5.3", "deepseek-v4-pro"],
  messages: [{ role: "user", content: "总结一下这段 diff。" }],
});
console.log(completion.model, completion.choices[0].message.content);

规则：

• 候选列表。 先 model，再按顺序取 models。重复项跳过，非字符串项忽略，总共最多尝试 5 个候选，其余丢弃。每个候选都按上面的规则解析名称。
• 何时切换到下一个。 仅当某次尝试在发出任何响应字节之前失败，且状态码为 404、408、429 或任意 5xx 时。
• 何时不切换。 400、401、402、403、413 会直接返回，因为换任何模型都会失败。一旦发出任何字节（包括 SSE keep-alive 心跳），响应即已确定，不会再尝试其他模型。
• 全部失败时。 返回最后一个候选的错误。
• 转发。 models 字段在发往上游前会被移除。
• 计费。 只对成功的那次尝试计费。

#应用识别请求头

与 OpenRouter 一样，发送 HTTP-Referer（应用 URL）和 X-Title（应用名称）。没有 X-Title 时会使用 X-OpenRouter-Title。它们不影响路由和价格。记录了什么，见应用识别。

#不支持的功能

• provider 对象（order、allow_fallbacks、only、ignore、sort、价格上限等）。不会被解析，由 Key 的分组决定哪个上游处理模型。
• transforms（如 middle-out）。不会被解析，长提示词不会被自动压缩。
• route（如 "fallback"）。不会被解析，请使用 models 数组。

请去掉这些字段。在 GLM、DeepSeek 分组上，请求体除 model 外原样转发，供应方可能拒绝未知字段。

OpenRouter 独有的其他功能，如额度查询接口、生成记录查询，在 BigModel.io 上不存在。查询 Key 用量请用 GET /v1/usage，逐条请求记录见用量页面。

#验证配置

把备选示例的第一个模型故意写错，例如 "model": "kimi-k3-typo"。请求应当仍然成功，用量页面中这条请求的模型应显示为 glm-5.3（第一个备选），且只对成功的尝试计费。

#常见问题排查

使用 provider/model 名称时返回 503「No available accounts」。 所有变体都不在 Key 的分组中。请使用模型目录中的普通 ID。

没有切换到备选模型。 第一个模型返回的状态码不触发备选（400、401、402、403、413），或流已经开始。请检查状态码。

只尝试了部分备选模型。 包括 model 在内最多 5 个候选，请缩短列表。

400 提到 provider、transforms 或 route。 上游拒绝了 BigModel.io 不解析的字段，请去掉它。

找不到 :free 模型。 :free 永远不会被去掉，请使用目录中存在的 ID。

#相关文档

• 从 OpenRouter 迁移：更换 Base URL 和 Key。
• 模型 ID与应用识别。
• Chat Completions API 参考。