# 从 OpenRouter 迁移

> 只需更换 Base URL 和 Key，即可把 OpenRouter 代码迁到 BigModel.io。provider/model 格式的模型 ID、models 回退数组和 HTTP-Referer / X-Title 应用标识都继续可用。

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

BigModel.io 在 `/v1/chat/completions`、`/v1/messages`、`/v1/responses` 上兼容 OpenRouter 的主要请求约定，大多数 OpenRouter 集成只需更换 Base URL 和 Key。

| | OpenRouter | BigModel.io |
|---|---|---|
| Base URL | `https://openrouter.ai/api/v1` | `https://bigmodel.io/v1` |
| API Key | `sk-or-...` | 在 [API Keys](https://bigmodel.io/keys) 创建的 BigModel.io Key |
| 端点 | `/chat/completions`、`/responses`、`/messages` | `/v1` 下的相同路径，具体取决于 Key 所在分组 |
| 模型 ID | `provider/model` | `glm-5.3` 这样的纯 ID；也接受 `provider/model` |
| 回退 | `models` 数组 | `models` 数组，总共最多 5 个模型 |
| 计费 | 美元额度 | 美元余额，各模型价格见 [/models](https://bigmodel.io/zh-cn/models) |

```python [Python]
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://bigmodel.io/v1",       # 原来是 https://openrouter.ai/api/v1
    api_key=os.environ["BIGMODEL_API_KEY"],  # 原来是 OPENROUTER_API_KEY
)
```

```js [Node.js]
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://bigmodel.io/v1",        // 原来是 https://openrouter.ai/api/v1
  apiKey: process.env.BIGMODEL_API_KEY,     // 原来是 OPENROUTER_API_KEY
});
```

## 带提供方前缀的模型名

可以继续使用 OpenRouter 风格的 ID。`z-ai/glm-5.3`、`deepseek/deepseek-v4-pro:nitro` 这样的名称会解析为 Key 所在分组提供的模型：

1. 分组直接提供该名称时，原样使用。
2. 否则依次尝试：去掉路由后缀（`:nitro`、`:floor`、`:exacto`）、去掉 `provider/` 前缀，再把这两种形式中的点换成短横线。
3. 都匹配不上时，按原名发送，并返回常规的"模型不可用"错误（503 `api_error`）。

`:free` 永远不会被去掉：`:free` 请求不会被悄悄换成付费模型。不含 `/` 或 `:` 的纯名称不会被改写。纯 ID 写法见[模型 ID](https://bigmodel.io/zh-cn/docs/model-ids)。

## 用 models 数组回退

把 `models` 作为有序回退列表发送。连同 `model` 在内，每个请求最多尝试 5 个模型（自动去重）。

```python [Python]
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Summarize this diff."}],
    extra_body={"models": ["glm-5.3", "deepseek-v4-pro"]},
)
print(completion.model)
```

```js [Node.js]
const completion = await client.chat.completions.create({
  model: "kimi-k3",
  models: ["glm-5.3", "deepseek-v4-pro"],
  messages: [{ role: "user", content: "Summarize this diff." }],
});
```

当某次尝试在**发出任何响应字节之前**返回 404、408、429 或 5xx 时，会尝试下一个模型。流式输出一旦开始就不再回退。400、401、402、403、413 会直接返回。`models` 字段在转发上游前会被移除，只对成功的那次尝试计费。

## 应用标识请求头

和 OpenRouter 一样，`HTTP-Referer` 与 `X-Title`（或 `X-OpenRouter-Title`）用于标识你的应用。BigModel.io 会为成功的请求按天记录 referer 的主机名和标题（最多 100 个字符），不会保存路径和查询参数。

```python [Python]
client = OpenAI(
    base_url="https://bigmodel.io/v1",
    api_key=os.environ["BIGMODEL_API_KEY"],
    default_headers={"HTTP-Referer": "https://your-app.example", "X-Title": "Your App"},
)
```

这些请求头可选，不影响路由和价格。目前没有面向用户的查看界面，详见[应用识别](https://bigmodel.io/zh-cn/docs/app-attribution)。

## 不支持的内容

- 不解析 `provider` 路由对象、`transforms` 和 `route`，依赖它们的请求会在忽略这些字段的情况下执行。
- 可用端点取决于分组：仅支持 Chat Completions 的 GLM、DeepSeek 分组访问 `/v1/messages` 和 `/v1/responses` 会返回 404。
- 其他 OpenRouter 专有字段请先测试再依赖。完整列表见 [OpenRouter 兼容](https://bigmodel.io/zh-cn/docs/openrouter-compat)。

## 验证配置

列出 Key 能调用的模型，与代码中使用的 ID 对照：

```bash
curl https://bigmodel.io/v1/models -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

再从应用发一个真实请求，在[用量](https://bigmodel.io/usage)页确认模型和费用符合预期。

## 常见问题排查

**使用 `provider/model` 名称时返回 503 `api_error`：`No available accounts: no available accounts supporting model: ...`。** 各种名称变体都不在 Key 所在分组中。改用[模型目录](https://bigmodel.io/zh-cn/models)中的纯 ID，或换一个提供该模型的分组的 Key。

**一直没有触发回退。** 第一个模型返回的错误不会触发回退（400、401、402、403、413），或流式输出已经开始。到[用量](https://bigmodel.io/usage)页查看状态码。

**401 `INVALID_API_KEY`。** 仍在发送 OpenRouter 的 Key。BigModel.io 的 Key 在 [API Keys](https://bigmodel.io/keys) 创建。

**所有请求都返回 404。** Base URL 里还留着 OpenRouter 的 `/api/v1` 路径，改成 `https://bigmodel.io/v1`。

**404 `not_found_error`：`... platform only supports /v1/chat/completions`。** 代码用仅 Chat Completions 分组的 Key 调用了 `/v1/messages` 或 `/v1/responses`。改用 Chat Completions，或换其他分组的 Key。

**403 并提示余额不足。** 余额为 0 或以下，且该模型在你的分组中不是 $0。OpenRouter 的 `:free` ID 在这里不会映射到免费模型。到[余额与账单](https://bigmodel.io/purchase)充值，或调用[模型目录](https://bigmodel.io/zh-cn/models)中标为免费的模型。

## 相关文档

- [OpenRouter 兼容](https://bigmodel.io/zh-cn/docs/openrouter-compat)：所有支持的字段。
- [OpenAI SDK 与 LangChain](https://bigmodel.io/zh-cn/docs/openai-sdk-langchain)
- [计费与充值](https://bigmodel.io/zh-cn/docs/billing)：美元余额与价格说明。
- [Claude Code](https://bigmodel.io/zh-cn/docs/claude-code)、[Cursor](https://bigmodel.io/zh-cn/docs/cursor) 等编程工具指南。