# 按 Key 限额与预算

> 为每个 BigModel.io API Key 单独设置美元额度、5 小时/每日/每周消费上限、有效期和 IP 规则，并通过 GET /v1/usage 读取这些限制。

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

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

| 设置 | 作用 | 触发时返回 |
|---|---|---|
| 额度（USD） | 该 Key 的总消费上限，`0` 表示不限。可重置已用额度。 | 429 `API_KEY_QUOTA_EXHAUSTED` |
| 5h / 1d / 7d 限额（USD） | 每个时间窗口内的消费上限，`0` 表示不限。可重置窗口用量。 | 429 `rate_limit_exceeded` |
| 有效期 | 预设 7、30、90 天，或自定义日期 | 403 `API_KEY_EXPIRED` |
| IP 白名单 / 黑名单 | IP 或 CIDR 网段，每行一个 | 403 `ACCESS_DENIED` |
| 状态 | 启用或停用 Key | 401 `API_KEY_DISABLED` |
| 分组 | 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 的每分钟请求数或并发设置。频率和并发限制按账户和分组生效，见[限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)。

如需对所有 Key 统一封顶，可以在[余额与账单](https://bigmodel.io/purchase)中设置账户的每周和每月消费上限。达到上限后返回 402 `spend_cap_reached`，直到重置；见[计费与充值](https://bigmodel.io/zh-cn/docs/billing)。

## 用 GET /v1/usage 读取限额

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

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

```python [Python]
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"))
```

```js [Node.js]
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"`。简化示例：

```json
{
  "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 参考](https://bigmodel.io/zh-cn/docs/api-usage)。

## 验证配置

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

## 常见问题排查

**429 `API_KEY_QUOTA_EXHAUSTED`。** Key 的总额度已用完。在 [API Keys](https://bigmodel.io/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](https://bigmodel.io/keys) 中启用。

## 相关文档

- [认证与 API Key](https://bigmodel.io/zh-cn/docs/authentication)：创建和发送 Key。
- [限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)：账户和分组限制。
- [Usage API 参考](https://bigmodel.io/zh-cn/docs/api-usage)与[错误码](https://bigmodel.io/zh-cn/docs/errors)。