认证与 API Key

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

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

#创建 Key

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

export BIGMODEL_API_KEY="sk-..."

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

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

#发送 Key

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"}]}'

import os
from openai import OpenAI

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

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 中编辑：

ACCESS_DENIED 的提示有意写得很笼统；如果设置过 IP 规则，先检查它。建议每个应用或环境使用单独的 Key，这样可以单独限额、轮换或停用。详见 按 Key 限额与预算。

#验证配置

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

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 重新复制，注意多余的空格或引号。

401 USER_NOT_FOUND 或 USER_INACTIVE。 Key 所属账户不存在或未启用。请联系 支持。

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 或已为负。见 计费与充值。

#相关文档

• 错误码
• 限额与速率
• 按 Key 限额与预算
• API 快速开始