查询余额与额度
查询这把密钥此刻还能花多少,以及它的额度;不计费,不要求余额为正。
/v1/usagebalance 是这把密钥此刻还能花的额度:密钥没设额度即账户余额,设了额度即密钥剩余额度;团队成员与部门的密钥还会再按本期剩余额度封顶。设了额度的密钥仍从账户余额扣费——账户余额先用完时,即使 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 双币字段只属于本接口),见扣费。
请求头
Bearer sk-…:控制台「API 密钥」里创建的密钥,所属分组须包含请求的模型
返回
200余额与额度;密钥过期或成员停用时也是 200,is_active: false
balance 大于 0 时为 true
这把密钥此刻还能花的额度(美元)
与 balance 相同
恒为 "USD",与 ledger_currency 一致
不带后缀金额的币种,为 "USD"(2026-10-01 之前为 "CNY")
balance 的人民币金额
balance 的美元金额
密钥额度
与 balance 相同
密钥剩余额度;没设额度时等于账户余额
密钥额度;0 表示没设额度
这把密钥累计已扣费金额
密钥没设额度时为 true
人民币
美元
没设额度时为 null
没设额度时为 null
没设额度时为 null
没设额度时为 null
人民币
美元
仅异常时:api key expired、member disabled 等
这把密钥所属的分组;专属分组不返回此字段
分组 ID
分组名称
各语言的分组名称,键为语言代码(如 en、zh-tw、es、ja),与控制台显示一致
分组的协议族,例如 openai、claude、gemini
错误
sk- 开头:missing or invalid api key;密钥不存在或已停用:invalid api key