# OpenRouter 兼容

> BigModel.io 支持哪些 OpenRouter 约定：provider/model 名称、路由后缀、models 备选数组、HTTP-Referer 与 X-Title，以及哪些字段会被忽略。

网页版: https://bigmodel.io/zh-cn/docs/openrouter-compat · 更新于 2026-10-18

BigModel.io 在 `/v1/chat/completions`、`/v1/messages` 和 `/v1/responses` 上支持 OpenRouter 的主要请求约定。本页是精确的规则说明；如需逐步迁移，请看[从 OpenRouter 迁移](https://bigmodel.io/zh-cn/docs/migrate-from-openrouter)。

| OpenRouter 功能 | 在 BigModel.io 上 |
|---|---|
| `provider/model` 形式的 ID，如 `z-ai/glm-5.3` | 支持：解析为分组提供的模型 |
| 路由后缀 `:nitro`、`:floor`、`:exacto` | 完整名称不可用时去掉 |
| `:free` 后缀 | 保留，永不去掉 |
| `models` 备选数组 | 支持，每个请求最多 5 个模型 |
| `HTTP-Referer`、`X-Title`、`X-OpenRouter-Title` | 记录为应用识别信息 |
| `provider` 对象、`transforms`、`route` | **不支持** |

## 模型名称如何解析

不含 `/` 或 `:` 的普通名称（如 `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](https://bigmodel.io/zh-cn/docs/model-ids)。

## 用 models 数组做备选

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

```bash [cURL]
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。"}]
  }'
```

```python [Python]
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)
```

```js [Node.js]
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`。它们不影响路由和价格。记录了什么，见[应用识别](https://bigmodel.io/zh-cn/docs/app-attribution)。

## 不支持的功能

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

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

OpenRouter 独有的其他功能，如额度查询接口、生成记录查询，在 BigModel.io 上不存在。查询 Key 用量请用 [GET /v1/usage](https://bigmodel.io/zh-cn/docs/api-usage)，逐条请求记录见[用量](https://bigmodel.io/usage)页面。

## 验证配置

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

## 常见问题排查

**使用 `provider/model` 名称时返回 503「No available accounts」。** 所有变体都不在 Key 的分组中。请使用[模型目录](https://bigmodel.io/zh-cn/models)中的普通 ID。

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

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

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

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

## 相关文档

- [从 OpenRouter 迁移](https://bigmodel.io/zh-cn/docs/migrate-from-openrouter)：更换 Base URL 和 Key。
- [模型 ID](https://bigmodel.io/zh-cn/docs/model-ids)与[应用识别](https://bigmodel.io/zh-cn/docs/app-attribution)。
- [Chat Completions API 参考](https://bigmodel.io/zh-cn/docs/api-chat-completions)。