残高とクォータを照会

このキーで現時点でいくら使えるか、およびそのクォータを照会します。課金されず、残高がプラスである必要もありません。

GET/v1/usage

balance はこのキーで現時点で使える額です。キーにクォータを設定していなければアカウント残高、設定していればキーの残りクォータになります。チームメンバーや部門のキーは、さらに当期の残りクォータで上限がかかります。クォータを設定したキーもアカウント残高から差し引かれるため、アカウント残高が先に尽きると、balance に余裕があってもリクエストは 402 を返します。

現在は人民元で記帳していますが、unit は "USD" と表示されます：balance、remaining、サフィックスのない quota.* はすべて人民元の数値です。照合には _cny / _usd フィールドを直接読んでください（_usd = _cny ÷ 6.8、固定）。このエンドポイントは Authorization: Bearer のみを受け付け、標準のエラー構造を使いません。HTTP ステータスコードだけでなく is_active で判定してください。

非同期タスクの照会では、タスク終了後にルートオブジェクトの 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

ヘッダー

レスポンス

エラー

関連ページ