跳到正文

查询余额与额度

查询这把密钥此刻还能花多少,以及它的额度;不计费,不要求余额为正。

GET/v1/usage

balance 是这把密钥此刻还能花的额度:密钥没设额度即账户余额,设了额度即密钥剩余额度;团队成员与部门的密钥还会再按本期剩余额度封顶。设了额度的密钥仍从账户余额扣费——账户余额先用完时,即使 balance 还有额度,请求也会返回 402。

金额以美元计价(2026-10-01 起 ledger_currency 为 "USD",与 unit 一致):balance、remaining 和不带后缀的 quota.* 都是美元金额;需要人民币时读 _cny 字段(对应 _usd 金额的人民币金额,固定换算,不是实时汇率)。本端点只认 Authorization: Bearer,且不使用标准错误结构:请以 is_active 判断,不要只看 HTTP 状态码。

异步任务查询在任务结束后的根对象 usage 里带单任务扣费:美元金额 cost_usd、人民币金额 cost 与 cost 的币种 currency,任务列表里每个终态任务的 usage 也带这些字段(上文的 _cny / _usd 双币字段只属于本接口),见扣费。

请求头

Authorization:必填string

Bearer sk-…:控制台「API 密钥」里创建的密钥,所属分组须包含请求的模型

返回

200余额与额度;密钥过期或成员停用时也是 200,is_active: false

is_active:可选boolean

balance 大于 0 时为 true

balance:可选number

这把密钥此刻还能花的额度(美元)

remaining:可选number

与 balance 相同

unit:可选string

恒为 "USD",与 ledger_currency 一致

ledger_currency:可选string

不带后缀金额的币种,为 "USD"(2026-10-01 之前为 "CNY")

balance_cny:可选number

balance 的人民币金额

balance_usd:可选number

balance 的美元金额

quota:可选object

密钥额度

message:可选string

仅异常时:api key expired、member disabled 等

group:可选object

这把密钥所属的分组;专属分组不返回此字段

错误

401没传密钥或不是 sk- 开头:missing or invalid api key;密钥不存在或已停用:invalid api key

相关页面