Account API

残高・クレジット・利用状況を API キーで参照します。

API キーに account:read 権限を付けると、残高やクレジットの有効期限、利用状況を API から参照できます。コンソールの「API キー」画面で、キーの作成時にチェックするか、既存のキーに後から付与してください。既定はオフです。

ベース URL は推論と同じ https://hai-api.hcloud.ltd です（/v1 は付きません）。認証は Authorization: Bearer のみで、x-api-key は使えません。

curl https://hai-api.hcloud.ltd/api/credits \
  -H "Authorization: Bearer $HAI_API_KEY"

curl 'https://hai-api.hcloud.ltd/api/usage?from=2026-08-01T00:00:00Z' \
  -H "Authorization: Bearer $HAI_API_KEY"

エンドポイント

エンドポイント	内容
`GET /api/me`	ユーザー情報と残高
`GET /api/credits`	残高とクレジットロット一覧（発行日・失効日・残額）
`GET /api/keys`	API キーの一覧（キー本体は返しません）と権限
`GET /api/usage`	期間の集計・モデル別内訳・新しい順 200 件の明細
`GET /api/usage/export`	UTC 月次の明細 CSV（`year` / `month`）

仕様

すべて参照のみです。チャージ、キーの作成・権限変更・無効化はコンソール（ログイン）からのみ行えます。
/api/usage の期間は from / to で指定します。いずれもタイムゾーン付きの RFC 3339（例 2026-08-01T00:00:00Z / 2026-08-01T09:00:00+09:00）で、from <= 利用日時 < to の半開区間です。省略時は全期間、未来の to はリクエスト時刻まで切り詰められます。
金額は 2 種類返ります。calculatedCostJpy はモデル単価から算出した額、debitedJpy は残高から実際に引かれた額です。どちらも円・小数 6 桁の文字列（例 "0.054600"）で、切り上げや最低額はありません。debitedJpy が "0.000000" になるのは、HAI Go の定額枠での利用分（calculatedCostJpy は参考額として記録されます）と、決済時点で有効なクレジットロットが無く実控除が無かった場合です。
残高が 0 でも参照できます。アカウントが停止中の場合は 403 です。
レート制限は IP 単位が 300 回/分、キー単位は JSON が 60 回/分・CSV が 2 回/分です。制限はハンドラ実行前に適用されるため、HTTP 400 も 1 回として数えます。超過時は 429 と Retry-After を返します。
ブラウザからの直接呼び出しは想定しておらず、CORS ヘッダーは付きません。サーバーや CLI から利用してください。