BigModel.io API 参考
BigModel.io OpenAI 与 Anthropic 兼容 API 的 Base URL、认证请求头、错误格式、请求 ID、流式输出和完整接口列表。
BigModel.io 用同一个 API Key 提供 OpenAI 和 Anthropic 两种 HTTP 协议。Key 能调用哪些接口和模型，取决于它所在的分组；下面每个接口的参考页都写明了适用的分组。
#Base URL
| 客户端类型 | Base URL | 实际请求地址 |
|---|---|---|
| OpenAI SDK 及 OpenAI 兼容工具 | https://bigmodel.io/v1 |
https://bigmodel.io/v1/chat/completions、/v1/responses、/v1/models 等 |
| Anthropic SDK、Claude Code | https://bigmodel.io（不带 /v1） |
客户端自己拼上 /v1/messages |
本参考中的路径都相对于 https://bigmodel.io/v1。
#认证
在 API Keys 创建 Key，并放在请求头里发送。网关按以下顺序检查，使用第一个出现的：
| 请求头 | 值 |
|---|---|
Authorization |
Bearer sk-...（Bearer 不区分大小写） |
x-api-key |
sk-...（Anthropic SDK 使用的方式） |
curl https://bigmodel.io/v1/models \
-H "Authorization: Bearer $BIGMODEL_API_KEY"不接受放在查询参数里的 Key：带 ?key= 或 ?api_key= 的请求会直接返回 400 api_key_in_query_deprecated，即使 Key 本身有效。没带 Key 返回 401 API_KEY_REQUIRED，Key 不存在返回 401 INVALID_API_KEY。
文本和模型接口要求余额大于 0 或有生效中的套餐，否则返回 403。例外是在 POST /v1/chat/completions、/v1/messages、/v1/responses 上调用标价 $0 的模型，余额为 0 时也可以（见 试用额度与免费模型）。如果设置了账户消费上限，达到上限时返回 402 spend_cap_reached。GET /v1/usage 和只读的视频接口不做这项检查。详见认证与 API Key 和计费与充值。
#接口列表
| 方法与路径 | 用途 | 适用分组 |
|---|---|---|
POST /v1/chat/completions |
OpenAI Chat Completions | 所有提供文本模型的分组 |
POST /v1/messages |
Anthropic Messages | Anthropic 分组；允许 Messages 调度的 OpenAI 分组。仅对话补全分组不可用 |
POST /v1/messages/count_tokens |
计算输入 token 数 | 仅 Anthropic 分组 |
POST /v1/responses |
OpenAI Responses（Codex CLI） | OpenAI 和 Anthropic 分组。仅对话补全分组不可用 |
GET /v1/models |
分组提供的模型 | 所有分组 |
POST /v1/videos |
创建视频、数字人或视频工具任务 | 按量付费的 Key |
GET /v1/videos/{id} |
查询任务状态和产物链接 | 创建该任务的同一账户 |
POST /v1/audio/speech |
配音 | 按量付费的 Key |
POST /v1/audio/generations |
音乐、音效、音频工具 | 按量付费的 Key |
POST /v1/workflows/short-drama |
剧本到成片工作流 | 按量付费的 Key |
GET /v1/usage |
Key 的额度、余额与用量 | 所有 Key |
"仅对话补全分组"指 DeepSeek、GLM 平台的分组。它们只提供 /v1/chat/completions，调用 /v1/messages、/v1/responses 和 token 计数会返回 404 not_found_error。
#错误
错误的 JSON 结构取决于是哪一层拒绝了请求：
| 层 | 结构 | 示例 |
|---|---|---|
| Key 与余额检查（路由之前） | {"code": "...", "message": "..."} |
INVALID_API_KEY、INSUFFICIENT_BALANCE |
/v1/messages、count_tokens、仅对话补全分组的 404 |
{"type": "error", "error": {"type": "...", "message": "..."}} |
not_found_error |
/v1/chat/completions、/v1/responses |
{"error": {"type": "...", "message": "..."}} |
rate_limit_error |
| 视频接口 | {"error": {"type": "<code>", "message": "..."}} |
insufficient_balance |
流式输出开始之后才发生的错误，会以 SSE error 事件返回，而不是 HTTP 状态码。分组不提供的模型或拼错的模型 ID 会返回 503 api_error（"No available accounts"），而不是 404。完整错误码和处理方法见错误码。
#请求 ID
每个响应都带 X-Request-ID 响应头。如果你发送了 X-Request-ID，网关会原样返回；否则自动生成一个。部分上游路径会把它替换为模型服务商的请求 ID。建议记录到日志，联系工单支持时一并提供。
该响应头没有通过 CORS 暴露给浏览器。请从你的服务器调用 API，不要在前端代码里调用，以免泄露 Key。
#流式输出
在 Chat Completions、Messages 或 Responses 中设置 "stream": true 即可获得 SSE 流：
- Chat Completions：
chat.completion.chunk事件，以data: [DONE]结束。网关总会要求上游在最后返回用量。 - Messages：Anthropic 事件流（
message_start……message_stop）。 - Responses：Responses 事件流（
response.created……response.completed）。GET /v1/responses是 WebSocket 通道，不带Upgrade请求头时返回426。
详见流式输出。
#限制
- 请求体最大 256 MiB，超过返回
413。创建视频的请求体最大 1 MiB。 - 并发和每分钟请求数按用户和分组限制；按 Key 的额度和消费限额是可选的。详见限额与速率和按 Key 限额与预算。
- 网关自身不发送限流响应头；上游的
x-ratelimit-*和retry-after如果存在会原样透传。
#OpenAPI 文件
这些接口的机器可读描述位于 https://bigmodel.io/openapi.json（OpenAPI 3.1），各参考页的请求和响应表格就是由它生成的。可以导入 Postman、Insomnia 或客户端代码生成器。
#常见问题排查
400 api_key_in_query_deprecated：Key 放在了 URL 里。去掉 ?key= / ?api_key=，改用 Authorization: Bearer。
/v1/messages 或 /v1/responses 返回 404 not_found_error：Key 属于仅对话补全分组。改用 /v1/chat/completions，或换一个提供该接口的分组的 Key。
403 INSUFFICIENT_BALANCE：余额为 0 或已为负。到充值页面充值。
#相关文档
更新于 · 以 Markdown 查看