# 认证与 API Key

> 如何发送 BigModel.io API Key、支持哪些请求头，Key 的分组、额度、有效期和 IP 规则如何生效，以及如何排查 401 和 403 错误。

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

BigModel.io 的每个请求都用控制台里的 API Key 认证。Key 放在请求头中，网关会在把请求路由到模型之前先校验它。

| 请求头 | 示例 | 常见使用方 |
|---|---|---|
| `Authorization` | `Bearer sk-...` | OpenAI SDK、多数工具、Claude Code 的 `ANTHROPIC_AUTH_TOKEN` |
| `x-api-key` | `sk-...` | Anthropic SDK 与客户端 |
| `x-goog-api-key` | `sk-...` | Gemini 风格客户端 |

同时存在多个时，优先级为 `Authorization` > `x-api-key` > `x-goog-api-key`。`Bearer` 不区分大小写。

## 创建 Key

1. 登录并打开 [API Keys](https://bigmodel.io/keys)。
2. 点击创建，填写名称并选择**分组**。分组决定 Key 可调用的模型、端点和倍率。
3. 按需设置额度、消费窗口、有效期和 IP 规则（见下文）。
4. 复制 Key，保存为环境变量。

```bash
export BIGMODEL_API_KEY="sk-..."
```

Key 的格式是 `sk-` 加 64 位十六进制字符。也可以自定义 Key：至少 16 个字符，只能包含字母、数字、`_` 和 `-`。

Key 并不是只显示一次。列表中显示脱敏形式（前 6 位和后 4 位），复制按钮随时可以复制完整 Key。拿到 Key 的人就能消耗你的余额，请只在服务端使用，不要提交到仓库或写进前端代码。

## 发送 Key

```bash [cURL]
curl https://bigmodel.io/v1/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"glm-5.3","messages":[{"role":"user","content":"ping"}]}'
```

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

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])
```

```js [Node.js]
import Anthropic from "@anthropic-ai/sdk";

// Anthropic SDK 发送 x-api-key；根地址不带 /v1。
const client = new Anthropic({ baseURL: "https://bigmodel.io", apiKey: process.env.BIGMODEL_API_KEY });
```

不要把 Key 放在 URL 中。`?key=` 或 `?api_key=` 会被拒绝，返回 400 `api_key_in_query_deprecated`。

## 分组

每个 Key 只属于一个分组，在创建时选择。分组决定：

- **模型。** 只能调用分组提供的模型，没有按 Key 设置的模型白名单。
- **端点。** GLM、DeepSeek 分组只提供 `/v1/chat/completions`，调用 `/v1/messages`、`/v1/messages/count_tokens` 和 `/v1/responses` 会返回 404。Anthropic 分组原生提供 `/v1/messages`，并转换 Chat Completions 请求。OpenAI 分组提供 Chat Completions 和 Responses，并在分组允许时转换 `/v1/messages`。
- **倍率。** 实际扣费为模型价格乘以分组倍率，专属费率可替代分组倍率。

没有分组的 Key 会返回 403 `permission_error`“API Key is not assigned to any group”。编辑 Key 并选择分组即可。

## Key 的单独设置

每个 Key 都能在 [API Keys](https://bigmodel.io/keys) 中编辑：

| 设置 | 作用 | 触发时的错误 |
|---|---|---|
| 状态 | 启用或停用 Key | 401 `API_KEY_DISABLED` |
| 额度（美元） | 总消费上限，0 表示不限；已用额度可重置 | 429 `API_KEY_QUOTA_EXHAUSTED` |
| 消费窗口（美元） | 每 5 小时、1 天、7 天的上限，0 表示不限 | 429 `rate_limit_exceeded` |
| 有效期 | 7 / 30 / 90 天或自定义日期 | 403 `API_KEY_EXPIRED` |
| IP 白名单 / 黑名单 | IP 或 CIDR，每行一个 | 403 `ACCESS_DENIED` |

`ACCESS_DENIED` 的提示有意写得很笼统；如果设置过 IP 规则，先检查它。建议每个应用或环境使用单独的 Key，这样可以单独限额、轮换或停用。详见 [按 Key 限额与预算](https://bigmodel.io/zh-cn/docs/key-limits)。

## 验证配置

`GET /v1/usage` 可以在不产生费用的情况下检查 Key，Key 过期或额度用尽时也能调用：

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

根据 `isValid`、`status`、额度或余额以及 `expires_at`，可以判断 Key 是否会被接受。API Keys 中的**测试**操作也会从控制台发送一个测试请求。

## 常见问题排查

**401 `API_KEY_REQUIRED`。** 网关没收到 Key。检查请求头名称，以及发请求的进程里是否设置了环境变量。

**401 `INVALID_API_KEY`。** Key 错误或已删除。从 [API Keys](https://bigmodel.io/keys) 重新复制，注意多余的空格或引号。

**401 `USER_NOT_FOUND` 或 `USER_INACTIVE`。** Key 所属账户不存在或未启用。请联系 [支持](https://bigmodel.io/support)。

**403 `ACCESS_DENIED`。** 请求 IP 被 Key 的 IP 白名单或黑名单拦截。

**403 `permission_error`“not assigned to any group”。** 给 Key 分配分组。

**404 `... platform only supports /v1/chat/completions`。** Key 所在分组只提供 Chat Completions。Messages 或 Responses 客户端请换用其他分组的 Key。

**403 `INSUFFICIENT_BALANCE`。** 认证已通过，但余额为 0 或已为负。见 [计费与充值](https://bigmodel.io/zh-cn/docs/billing)。

## 相关文档

- [错误码](https://bigmodel.io/zh-cn/docs/errors)
- [限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)
- [按 Key 限额与预算](https://bigmodel.io/zh-cn/docs/key-limits)
- [API 快速开始](https://bigmodel.io/zh-cn/docs/quickstart)