按 Key 限额与预算

每个 API Key 都可以有自己的预算和访问规则，这样把 Key 交给同事、脚本或客户时，不会危及整个账户余额。在 API Keys 页面创建或编辑 Key 时设置。

所有限额都按乘以分组倍率后的实际费用（美元）计算。无论 Key 自身限额如何，账户余额用完后 Key 也会停止工作（403 INSUFFICIENT_BALANCE）。

#消费窗口如何计算

5 小时、1 天、7 天限额使用固定窗口，而不是滚动窗口。上一个窗口结束后，Key 第一次被使用时开始新窗口，满一个完整时长后重置。例如每日限额 $5 的 Key 在 14:00 首次使用，可以消费 $5 直到次日 14:00，之后重新获得 $5。

窗口额度用完后，请求返回 HTTP 429，错误类型为 rate_limit_exceeded，消息类似 api key 5小时限额已用完。响应不带 Retry-After 头，请从 /v1/usage 读取 reset_at 判断何时恢复。

正在进行的请求可以完成并略微超出限额，下一个请求会被拦截。

#Key 无法限制的内容

• 模型。 没有按 Key 的模型白名单，Key 可以调用其分组提供的所有模型。如需限制模型，请使用其他分组的 Key。
• 请求频率。 没有按 Key 的每分钟请求数或并发设置。频率和并发限制按账户和分组生效，见限额与速率。

如需对所有 Key 统一封顶，可以在余额与账单中设置账户的每周和每月消费上限。达到上限后返回 402 spend_cap_reached，直到重置；见计费与充值。

#用 GET /v1/usage 读取限额

GET /v1/usage 返回当前 Key 的限额和用量。即使 Key 已过期或额度用完也能调用，脚本随时可以查明停止原因。

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

import os, requests

r = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=10,
)
data = r.json()
print(data.get("status"), data.get("remaining"))
for w in data.get("rate_limits", []):
    print(w["window"], w["used"], "/", w["limit"], "resets", w.get("reset_at"))

const r = await fetch("https://bigmodel.io/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}` },
});
const data = await r.json();
console.log(data.status, data.remaining);
for (const w of data.rate_limits ?? []) console.log(w.window, w.used, "/", w.limit, "resets", w.reset_at);

设置了额度或消费窗口的 Key 返回 "mode": "quota_limited"。简化示例：

{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 3.42, "remaining": 16.58, "unit": "USD"},
  "remaining": 16.58,
  "unit": "USD",
  "rate_limits": [
    {"window": "1d", "limit": 5, "used": 1.2, "remaining": 3.8,
     "window_start": "2026-10-18T06:00:00Z", "reset_at": "2026-10-19T06:00:00Z"}
  ],
  "expires_at": "2026-11-17T00:00:00Z",
  "days_until_expiry": 30,
  "usage": {"today": {"requests": 12, "cost": 0.4, "actual_cost": 0.4}, "total": {"requests": 310}}
}

• status 为 active、quota_exhausted、expired 或 disabled。
• 只有设置了额度才有 quota；rate_limits 只列出已设置的窗口。窗口尚未开始或已结束时没有 reset_at。
• 没有额度和消费窗口的 Key 返回 "mode": "unrestricted"，remaining 为账户余额（套餐分组则为套餐限额）。该模式不包含有效期。
• usage 包含 today 和 total 的请求数、token 和费用。加上 ?start_date=2026-10-01&end_date=2026-10-18 可设置 model_stats 的日期范围（默认最近 30 天）。

完整结构见 Usage API 参考。

#验证配置

创建一个每日限额很小的 Key（例如 $0.10），用它调用 GET /v1/usage。响应应为 quota_limited，并列出 limit: 0.1 的 1d 窗口。发几个请求后再调用一次，used 会增加。API Keys 页面显示的数字与之一致。

#常见问题排查

429 API_KEY_QUOTA_EXHAUSTED。 Key 的总额度已用完。在 API Keys 中提高额度或重置已用额度。

429 rate_limit_exceeded，消息类似 api key 1天限额已用完。 5h、1d 或 7d 窗口额度已用完。等到 reset_at，提高限额，或重置该 Key 的窗口用量。

429 rate_limit_exceeded 且带有 Retry-After 头。 这是账户或分组的每分钟请求数限制，不是 Key 预算。等待 Retry-After 指定的秒数。

403 API_KEY_EXPIRED。 为 Key 设置更晚的有效期，或新建 Key。

403 ACCESS_DENIED。 调用方 IP 不在 Key 的白名单中，或在黑名单中。错误信息有意保持模糊。请检查服务器的出口 IP，也可以填写 CIDR 网段。

401 API_KEY_DISABLED。 Key 已停用，在 API Keys 中启用。

#相关文档

• 认证与 API Key：创建和发送 Key。
• 限额与速率：账户和分组限制。
• Usage API 参考与错误码。