查询 Key 的额度、余额与用量

BigModel.io 的 GET /v1/usage 接口：返回当前 Key 的余额或额度、5 小时/1 天/7 天消费窗口、过期时间和 token 用量。Key 过期或额度用完后仍可调用。

GEThttps://bigmodel.io/v1/usage

本页目录

请求
认证
查询参数
响应
响应字段
示例
使用账户余额的 Key
设置了额度和消费窗口的 Key
说明
相关文档

返回当前 Key 还剩多少、用了多少：账户余额、套餐额度或 Key 自己的额度、消费窗口、过期时间和 token 统计。任何 Key 都能调用，而且不做计费检查，所以 CC Switch 等工具在 Key 过期或额度用完后仍能显示原因。返回字段随 mode 不同。

#请求

http

GET https://bigmodel.io/v1/usage

#认证

请求头	值
`Authorization`	`Bearer $BIGMODEL_API_KEY`
`x-api-key`	`$BIGMODEL_API_KEY`

任选其一。

#查询参数

名称	类型	必填	说明
`start_date`	string		`model_stats` 统计起始日期（YYYY-MM-DD），默认 30 天前。
`end_date`	string		`model_stats` 统计结束日期（YYYY-MM-DD），默认今天。

#响应

状态码	含义
`200`	Key 的用量。字段随 `mode` 不同。
`400`	`api_key_in_query_deprecated`：Key 放在了 `?key=` 或 `?api_key=` 里，请改用请求头。
`401`	`API_KEY_REQUIRED`、`INVALID_API_KEY`、`API_KEY_DISABLED`、`USER_NOT_FOUND`、`USER_INACTIVE`。
`403`	`ACCESS_DENIED`（IP 规则）或 `permission_error`（Key 未分配分组）。

#响应字段

字段	类型	说明
`mode`	string	Key 设置了自己的额度或限额时为 `quota_limited`，否则为 `unrestricted`（使用账户余额或套餐）。可选值：`quota_limited`, `unrestricted`
`isValid`	boolean	Key 处于正常、额度用完或已过期时都为 true，具体看 `status`。
`status`	string	仅 `quota_limited`：`active`、`quota_exhausted`、`expired` 等。
`planName`	string	仅 `unrestricted`：套餐（分组）名或钱包余额。
`remaining`	number	剩余美元：Key 额度、余额，或套餐各周期中最小的剩余额度（无限制时为 `-1`）。
`unit`	any
`balance`	number	使用余额时的钱包余额（美元）。
`quota`	object	设置了额度的 `quota_limited` Key。
`quota.limit`	number
`quota.used`	number
`quota.remaining`	number
`quota.unit`	any
`rate_limits`	array<object>	Key 上设置的消费窗口。
`rate_limits[].window`	string	可选值：`5h`, `1d`, `7d`
`rate_limits[].limit`	number
`rate_limits[].used`	number
`rate_limits[].remaining`	number
`rate_limits[].window_start`	string
`rate_limits[].reset_at`	string
`expires_at`	string	Key 过期时间（如有）。
`days_until_expiry`	integer
`subscription`	object	套餐的额度与已用（美元）。
`subscription.daily_usage_usd`	number
`subscription.weekly_usage_usd`	number
`subscription.monthly_usage_usd`	number
`subscription.daily_limit_usd`	number
`subscription.weekly_limit_usd`	number
`subscription.monthly_limit_usd`	number
`subscription.expires_at`	string
`usage`	object	该 Key 的 token 用量，暂不可用时省略。
`usage.today`	object
`usage.total`	object
`usage.average_duration_ms`	number
`usage.rpm`	number
`usage.tpm`	number
`model_stats`	array<object>	日期范围内的分模型用量，暂不可用时省略。

#示例

cURL

curl "https://bigmodel.io/v1/usage?start_date=2026-10-01&end_date=2026-10-18" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"

Python

import os, requests

usage = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=30,
).json()
print(usage["mode"], usage.get("remaining"), usage.get("unit"))

Node.js

const usage = await (await fetch('https://bigmodel.io/v1/usage', {
  headers: {Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}`},
})).json()
console.log(usage.mode, usage.remaining, usage.unit)

#使用账户余额的 Key

数值仅作示意。usage 只保留了 today，total 字段相同。

json

{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 12.5,
  "unit": "USD",
  "balance": 12.5,
  "usage": {
    "today": {"requests": 42, "input_tokens": 51200, "output_tokens": 8300, "cache_creation_tokens": 0, "cache_read_tokens": 20480, "total_tokens": 79980, "cost": 0.091, "actual_cost": 0.091},
    "average_duration_ms": 2350,
    "rpm": 0,
    "tpm": 0
  }
}

#设置了额度和消费窗口的 Key

数值仅作示意；时间戳使用服务器时区。

json

{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 4.2, "remaining": 15.8, "unit": "USD"},
  "remaining": 15.8,
  "unit": "USD",
  "rate_limits": [
    {"window": "5h", "limit": 2, "used": 0.6, "remaining": 1.4, "window_start": "2026-10-18T08:00:00+08:00", "reset_at": "2026-10-18T13:00:00+08:00"}
  ],
  "expires_at": "2026-11-17T00:00:00+08:00",
  "days_until_expiry": 30
}

#说明

三种结构。 Key 设置了自己的额度或 5 小时/1 天/7 天消费限额时为 quota_limited；Key 所在分组按生效中的套餐计费时为带 subscription 的 unrestricted；其他情况为带 balance 的 unrestricted。余额模式下 planName 固定为字符串 钱包余额。
remaining 单位是美元：Key 额度、账户余额，或套餐各周期中最小的剩余额度（套餐无限制时为 -1）。
quota_limited 模式下，Key 过期或额度用完时 isValid 仍为 true。 请查看 status（active、quota_exhausted、expired）和 days_until_expiry 判断 Key 能否继续请求。
消费窗口是固定窗口，不是滚动窗口。 窗口从首次使用时开始，满时长后重置；只有窗口进行中才有 reset_at。详见按 Key 限额与预算。
用量统计尽力返回。 统计不可用时省略 usage 和 model_stats。start_date / end_date（YYYY-MM-DD）只影响 model_stats，默认最近 30 天。cost 按标价计算，actual_cost 是实际扣费。
并非所有检查都跳过。 已禁用的 Key 仍返回 401 API_KEY_DISABLED，IP 规则仍然生效。完整列表见错误码。
需要逐条请求明细或导出 CSV，请使用控制台的用量页面。

#相关文档

这篇文档有帮助吗？

更新于 2026-10-18 · 以 Markdown 查看