API キーで残高を照会する

sk- で始まる API キーを使って、現在のキーの残りクォータと利用可否を直接照会できます。サードパーティクライアントが UI に残高を表示したり、スクリプトで残高を監視したりする用途に向いています。

1. エンドポイント一覧

2. どの残高が返るか

balance は必ずしもアカウントのウォレット残高ではなく、現在のキーが実際に利用できる残りクォータです。次の順に最初に当てはまるものが採用されます。

また is_active は、このキーが現在業務リクエストに使えるかを示します。キーのステータスが有効で、期限切れでなく、総クォータを使い切っていない場合に true になります。サブスクリプショングループに属していて有効なサブスクリプションがない場合も false です。

3. GET /v1/user/balance

GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

レスポンス — ウォレット残高モード（キーにクォータがなく、サブスクリプショングループでもない）：

{
  "is_active": true,
  "balance": 1575.13,
  "unit": "USD"
}

レスポンス — キーに総クォータがある場合（used と total が追加されます）：

{
  "is_active": true,
  "balance": 6,
  "unit": "USD",
  "used": 4,
  "total": 10
}

レスポンス — 回数制のサブスクリプショングループ：

{
  "is_active": true,
  "balance": 842,
  "unit": "requests"
}

レスポンスフィールド

4. GET /v1/credits

OpenRouter 形式の残高フォーマットです。クライアントは total_credits - total_usage で残りクォータを表示します。

GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

レスポンス：

{
  "data": {
    "total_credits": 20,
    "total_usage": 4
  }
}

5. サードパーティクライアントでの設定

curl -s https://api.lmuai.com/v1/user/balance \
  -H "Authorization: Bearer sk-xxxxxxxx"

6. エラーレスポンス

残高照会はゲートウェイ共通の API キー認証を使うため、エラーは他の API 呼び出しと同じ形式で返ります。リクエストにキーがない場合：

{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}

一般的なエラーはエラーコードを参照してください。

7. 「使用状況詳細のエクスポート」との違い

GET /v1/usage はその中間にあたるエンドポイントです。同じく sk- キーを使い、現在のキーの当日・累計の使用状況統計とクォータ情報を返します。フィールドはより詳細です。

最終更新：2026-11-05

京ICP备2020034311号-7