查詢餘額與額度

查詢這把金鑰此刻還能花多少，以及它的額度；不計費，不要求餘額為正。

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

請求標頭

回傳

錯誤

相關頁面