# 残高 API

Source: https://docs.aiand.com/ja/billing/balance/

```http
GET /billing/balance
```

組織のプリペイドクレジット残高 — コンソールの請求ページに表示されているのと同じ値 — を返します。残高が減ってきたら、リクエストが `402 Payment Required` で失敗し始める前に通知する、といったスクリプトから利用してください。

## レスポンス

```json
{
  "balance": "42.75000000",
  "currency": "usd"
}
```

| フィールド | 型     | 説明                                     |
| ---------- | ------ | ---------------------------------------- |
| `balance`  | string | 請求通貨建ての残高。10 進数の文字列。    |
| `currency` | string | `usd` または `jpy`。組織の請求通貨です。 |

`balance` は精度を落とさないよう文字列で返します。float ではなく decimal ライブラリで解釈してください。

## この値の意味

残高は **確定済み** の台帳の値です。そのため、実際に使える額より一時的に大きく見えることがあります:

- チャットや補完のリクエストは完了後、非同期の精算キューを経由して差し引かれます。通常は数秒の遅延です。精算が滞留・リトライしている場合はさらに遅れます。
- 動画生成は受け付け時にクレジットを予約しますが、差し引かれるのはレンダリング完了時です。待機中・実行中のレンダリングはまだ反映されていません。
- 処理中のリクエストによって残高が一時的にわずかにマイナスになることがあります。次のチャージでまず相殺されます。

監視用途なら 1 分に 1 回のポーリングで十分です。閾値は上記の遅延を見込んで余裕を持たせてください。

## 認証

API キー、または JWT + `X-Org-ID`。[認証](/ja/authentication/) を参照。

API キーで呼び出した場合、返されるのは常にそのキーが属する組織の残高です。`X-Org-ID` は無視されます。

## 例

```bash
curl https://api.aiand.com/billing/balance \
  -H "Authorization: Bearer $AIAND_API_KEY"
```

<Aside type="note">
  API キーを受け付ける `/billing/` エンドポイントはこれだけです。
  購入、支払い方法、オートチャージ、リデンプションはコンソール専用のままです。
</Aside>