从 OpenRouter 迁移

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

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
)

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。

#用 models 数组回退

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

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)

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 个字符），不会保存路径和查询参数。

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"},
)

这些请求头可选，不影响路由和价格。目前没有面向用户的查看界面，详见应用识别。

#不支持的内容

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

#验证配置

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

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

再从应用发一个真实请求，在用量页确认模型和费用符合预期。

#常见问题排查

使用 provider/model 名称时返回 503 api_error：No available accounts: no available accounts supporting model: ...。 各种名称变体都不在 Key 所在分组中。改用模型目录中的纯 ID，或换一个提供该模型的分组的 Key。

一直没有触发回退。 第一个模型返回的错误不会触发回退（400、401、402、403、413），或流式输出已经开始。到用量页查看状态码。

401 INVALID_API_KEY。 仍在发送 OpenRouter 的 Key。BigModel.io 的 Key 在 API 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 在这里不会映射到免费模型。到余额与账单充值，或调用模型目录中标为免费的模型。

#相关文档

• OpenRouter 兼容：所有支持的字段。
• OpenAI SDK 与 LangChain
• 计费与充值：美元余额与价格说明。
• Claude Code、Cursor 等编程工具指南。