查询余额与额度

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

GET/v1/usage

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

目前按人民币记账，unit 却写着 "USD"：balance、remaining 和不带后缀的 quota.* 都是人民币数值。对账请直接读 _cny / _usd 字段（_usd = _cny ÷ 6.8，固定）。本端点只认 Authorization: Bearer，且不使用标准错误结构：请以 is_active 判断，不要只看 HTTP 状态码。

异步任务查询在任务结束后的根对象 usage 里带单任务扣费 cost / cost_cny / cost_usd，见扣费。

查询余额与额度

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer $HOPBASE_API_KEY"

200application/json

{
  "is_active": true,
  "balance": 54.4,
  "remaining": 54.4,
  "unit": "USD",
  "ledger_currency": "CNY",
  "exchange_rate": {
    "cny_per_usd": 6.8,
    "basis": "fixed unit rate"
  },
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 54.4,
    "api_key_remaining": 54.4,
    "total": 68,
    "used": 13.6,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

请求头

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:可选string

不带后缀金额的真实币种，目前为 "CNY"

exchange_rate:可选object

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

请求头

返回

错误

相关页面