# BigModel.io API 参考

> BigModel.io OpenAI 与 Anthropic 兼容 API 的 Base URL、认证请求头、错误格式、请求 ID、流式输出和完整接口列表。

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

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](https://bigmodel.io/keys) 创建 Key，并放在请求头里发送。网关按以下顺序检查，使用第一个出现的：

| 请求头 | 值 |
|---|---|
| `Authorization` | `Bearer sk-...`（`Bearer` 不区分大小写） |
| `x-api-key` | `sk-...`（Anthropic SDK 使用的方式） |

```bash
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 时也可以（见 [试用额度与免费模型](https://bigmodel.io/zh-cn/docs/free-credits)）。如果设置了账户消费上限，达到上限时返回 `402` `spend_cap_reached`。[`GET /v1/usage`](https://bigmodel.io/zh-cn/docs/api-usage) 和只读的视频接口不做这项检查。详见[认证与 API Key](https://bigmodel.io/zh-cn/docs/authentication) 和[计费与充值](https://bigmodel.io/zh-cn/docs/billing)。

## 接口列表

| 方法与路径 | 用途 | 适用分组 |
|---|---|---|
| [`POST /v1/chat/completions`](https://bigmodel.io/zh-cn/docs/api-chat-completions) | OpenAI Chat Completions | 所有提供文本模型的分组 |
| [`POST /v1/messages`](https://bigmodel.io/zh-cn/docs/api-messages) | Anthropic Messages | Anthropic 分组；允许 Messages 调度的 OpenAI 分组。仅对话补全分组不可用 |
| [`POST /v1/messages/count_tokens`](https://bigmodel.io/zh-cn/docs/api-count-tokens) | 计算输入 token 数 | 仅 Anthropic 分组 |
| [`POST /v1/responses`](https://bigmodel.io/zh-cn/docs/api-responses) | OpenAI Responses（Codex CLI） | OpenAI 和 Anthropic 分组。仅对话补全分组不可用 |
| [`GET /v1/models`](https://bigmodel.io/zh-cn/docs/api-models) | 分组提供的模型 | 所有分组 |
| [`POST /v1/videos`](https://bigmodel.io/zh-cn/docs/api-media-tasks) | 创建视频、数字人或视频工具任务 | 按量付费的 Key |
| [`GET /v1/videos/{id}`](https://bigmodel.io/zh-cn/docs/api-media-tasks) | 查询任务状态和产物链接 | 创建该任务的同一账户 |
| [`POST /v1/audio/speech`](https://bigmodel.io/zh-cn/docs/text-to-speech) | 配音 | 按量付费的 Key |
| [`POST /v1/audio/generations`](https://bigmodel.io/zh-cn/docs/audio-generation) | 音乐、音效、音频工具 | 按量付费的 Key |
| [`POST /v1/workflows/short-drama`](https://bigmodel.io/zh-cn/docs/short-drama-workflow) | 剧本到成片工作流 | 按量付费的 Key |
| [`GET /v1/usage`](https://bigmodel.io/zh-cn/docs/api-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`。完整错误码和处理方法见[错误码](https://bigmodel.io/zh-cn/docs/errors)。

## 请求 ID

每个响应都带 `X-Request-ID` 响应头。如果你发送了 `X-Request-ID`，网关会原样返回；否则自动生成一个。部分上游路径会把它替换为模型服务商的请求 ID。建议记录到日志，联系[工单支持](https://bigmodel.io/support)时一并提供。

该响应头没有通过 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`。

详见[流式输出](https://bigmodel.io/zh-cn/docs/streaming)。

## 限制

- 请求体最大 256 MiB，超过返回 `413`。创建视频的请求体最大 1 MiB。
- 并发和每分钟请求数按用户和分组限制；按 Key 的额度和消费限额是可选的。详见[限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)和[按 Key 限额与预算](https://bigmodel.io/zh-cn/docs/key-limits)。
- 网关自身不发送限流响应头；上游的 `x-ratelimit-*` 和 `retry-after` 如果存在会原样透传。

## OpenAPI 文件

这些接口的机器可读描述位于 [`https://bigmodel.io/openapi.json`](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 或已为负。到[充值](https://bigmodel.io/purchase)页面充值。

## 相关文档

- [快速开始](https://bigmodel.io/zh-cn/docs/quickstart)
- [认证与 API Key](https://bigmodel.io/zh-cn/docs/authentication)
- [错误码](https://bigmodel.io/zh-cn/docs/errors)
- [模型目录](https://bigmodel.io/zh-cn/models)