> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 残高照会API：AccessTokenで /api/user/self を呼び出す

> システムのAccessTokenを取得して /api/user/self を呼び出し、クォータのフィールドを読み取って米ドルに換算し、残高アラートに使う方法を説明します。

| 項目 | 内容 |
| - | - |
| エンドポイント | `GET https://api.laozhang.ai/api/user/self` |
| 認証 | `Authorization` ヘッダーにシステムのAccessTokenを指定 |
| 主なフィールド | 残りクォータ、使用済みクォータ、リクエスト数、アカウントのグループ |
| 換算 | `quota` を500,000で割ると、残高が米ドルで求まります。下の「クォータを米ドルに換算する」を参照 |

> [!NOTE]
>
> **AccessTokenは、モデルのリクエストに使うAPIキーとは別のもので、アカウントに対してより広い権限を持ちます。**
>
> * サーバー内の環境変数かシークレット管理ツールに保管してください。
> * ブラウザやクライアントアプリには含めないでください。

## AccessTokenの取得

**1. アカウント設定を開く**

コンソールにログインし、[アカウント設定](https://api.laozhang.ai/account/profile)を開きます。

**2. システムトークンのダイアログを開く**

**システムトークン**（System Token）を選び、コンソールからパスワードを求められたら入力します。

**3. AccessTokenをコピーする**

表示されたAccessTokenをすぐにコピーして、安全な場所に保管してください。新しいAccessTokenを生成すると以前のものが無効になることがあるため、使用中のサービスはすべて更新してください。

AccessTokenは、ソースコード、ブラウザアプリ、ログ、スクリーンショット、サポートへの問い合わせに含めないでください。サポートに相談するときは、リクエストの時刻、HTTPステータス、レスポンスのメッセージ、伏せ字にしたコマンドを送ってください。

## エンドポイント

```text theme={null}
GET https://api.laozhang.ai/api/user/self
Authorization: <your AccessToken>
```

このリクエストにクエリパラメーターやボディはなく、レスポンスはJSONです。以下の例のように、`Authorization` の値にはAccessTokenをそのまま指定します。`Accept: application/json` と `Content-Type: application/json` は省略できます。cURLでは、レスポンスを展開するために `--compressed` を付けることをおすすめします。

## レスポンス

成功すると、次のようなレスポンスが返ります。

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "id": 12345,
    "username": "demo_user",
    "display_name": "demo_user",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "default",
    "ModelFixedPrice": []
  }
}
```

| フィールド | 型 | 説明 |
| - | - | - |
| `success` | Boolean | リクエストが成功したかどうか |
| `message` | String または null | エラーメッセージ。成功時は通常 `null` |
| `data.quota` | Integer | 残りクォータ。アラートのしきい値に使います |
| `data.used_quota` | Integer | これまでに使用したクォータ |
| `data.request_count` | Integer | リクエストの累計数 |
| `data.group` | String | アカウントのグループ |
| `data.username` | String | ユーザー名 |
| `data.display_name` | String | 表示名 |
| `data.ModelFixedPrice` | Array | モデルの料金データ。残高だけが必要なら無視して構いません |
| `data.access_token` | String | 機密情報です。返された場合も、ログには書き込まないでください |

アカウントによっては、ほかのフィールドが含まれることがあります。必要なフィールドだけを読み取り、未知のフィールドはパーサーで無視してください。

## クォータを米ドルに換算する

`quota` と `used_quota` は、米ドルではなくクォータ単位で返されます。500,000クォータが約1米ドルです。

| 値 | 計算式 | サンプルレスポンスでの値 |
| - | - | - |
| 残高 | `quota ÷ 500,000` | `24997909 ÷ 500,000` ≈ 50.00米ドル |
| 使用額 | `used_quota ÷ 500,000` | `10027091 ÷ 500,000` ≈ 20.05米ドル |
| 残高と使用額の合計 | `(quota + used_quota) ÷ 500,000` | ≈ 70.05米ドル |

この換算は表示用です。リクエストの実際の料金は、モデルの料金、トークングループ、呼び出しログに表示される課金額で決まります。アラートに使う場合は、精度を保つため、換算後の金額と一緒に生の `quota` も保存してください。

## コード例

ターミナルで、プレースホルダーを置き換えてAccessTokenを一度だけ設定します。

```bash theme={null}
export LAOZHANG_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
```

> [tab] cURL
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json"
> ```
>
> `--compressed` を付けないと、ターミナルの出力が文字化けしたり、`jq` が `Invalid numeric literal` を報告したりすることがあります。

> [tab] cURL with jq
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" |
>   jq '.data | {
>     quota,
>     remaining_usd: (.quota / 500000),
>     used_quota,
>     used_usd: (.used_quota / 500000),
>     request_count,
>     group
>   }'
> ```

> [tab] Python
>
> `python -m pip install requests` で `requests` をインストールしてから実行してください。
>
> ```python theme={null}
> import os
> import requests
>
> response = requests.get(
>     "https://api.laozhang.ai/api/user/self",
>     headers={
>         "Accept": "application/json",
>         "Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"],
>         "Content-Type": "application/json",
>     },
>     timeout=10,
> )
> response.raise_for_status()
> payload = response.json()
> if not payload.get("success"):
>     raise SystemExit(f"残高の取得に失敗しました: {payload.get('message')}")
>
> account = payload["data"]
> quota_per_usd = 500_000
> print("quota:", account["quota"])
> print("remaining_usd:", round(account["quota"] / quota_per_usd, 2))
> print("used_quota:", account["used_quota"])
> print("used_usd:", round(account["used_quota"] / quota_per_usd, 2))
> print("request_count:", account["request_count"])
> print("group:", account.get("group"))
> ```
>
> `requests` は、gzipで圧縮されたレスポンスを自動的に展開します。

> [tab] Node.js
>
> このコードを `.mjs` ファイルに保存し、Node.js 18以降で実行してください。
>
> ```javascript theme={null}
> const response = await fetch("https://api.laozhang.ai/api/user/self", {
>   headers: {
>     Accept: "application/json",
>     Authorization: process.env.LAOZHANG_ACCESS_TOKEN,
>     "Content-Type": "application/json",
>   },
>   signal: AbortSignal.timeout(10_000),
> });
> if (!response.ok) {
>   throw new Error(`残高の取得に失敗しました: HTTP ${response.status}`);
> }
>
> const payload = await response.json();
> if (!payload.success) {
>   throw new Error(`残高の取得に失敗しました: ${payload.message}`);
> }
>
> const account = payload.data;
> const quotaPerUsd = 500_000;
> console.log({
>   quota: account.quota,
>   remaining_usd: Number((account.quota / quotaPerUsd).toFixed(2)),
>   used_quota: account.used_quota,
>   used_usd: Number((account.used_quota / quotaPerUsd).toFixed(2)),
>   request_count: account.request_count,
>   group: account.group,
> });
> ```

## エラー

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

`Authorization` ヘッダーが空、AccessTokenが不完全または無効になっている、あるいはAccessTokenではなくモデル用のAPIキーを送っている場合に発生します。原因ごとの対処は、[残高照会APIで401が返るときの対処](https://docs.laozhang.ai/en/faq/balance-query-api.md)にまとめています。

ステータスコードとレスポンスボディは、組み合わせて判断してください。

* `Authorization` ヘッダーがまったくない場合は、HTTP 401が返り、`code` が `AUTH_REQUIRED` になります。
* AccessTokenが誤っているか期限切れの場合は、**HTTP 200**で `success: false` が返り、AccessTokenが無効である旨のメッセージが付きます。

スクリプトでは、ステータスコードだけに頼らず、`success` を確認してください。

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "message": "Forbidden"
}
```

この認証情報にはこのエンドポイントへの権限がないか、アカウントについてサポートでの確認が必要です。

### 文字化け、またはjqのエラー

cURLの出力が文字化けする、または `jq` が `Invalid numeric literal` を報告する場合は、圧縮されたレスポンスが展開されていません。cURLのコマンドに `--compressed` を付けてください。

## 残高の監視

残高が減る前に気づけるように、このエンドポイントを定期的に確認します。次のスクリプトは、残高がしきい値を下回るとステータス1で終了します。

```python theme={null}
import os
import sys
import requests

THRESHOLD_USD = float(os.environ.get("LAOZHANG_ALERT_USD", "20"))

response = requests.get(
    "https://api.laozhang.ai/api/user/self",
    headers={"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
remaining_usd = response.json()["data"]["quota"] / 500000

if remaining_usd < THRESHOLD_USD:
    print(f"残高 ${remaining_usd:.2f} がしきい値 ${THRESHOLD_USD} を下回っています")
    sys.exit(1)
```

cronや監視システムから10〜30分おきに実行し、終了コードが0以外のときに通知を送ります。例：

```bash theme={null}
*/10 * * * * /usr/bin/python3 /opt/check_balance.py || /opt/notify.sh
```

cronはシェルの環境変数を読み込まないため、`LAOZHANG_ACCESS_TOKEN` はスクリプトかcrontabで渡してください。設定時の注意点は次のとおりです。

* `LAOZHANG_ACCESS_TOKEN` は、環境変数かシークレット管理ツールに保管する。
* リクエストのタイムアウトを、10秒などに設定する。
* 確認の間隔は控えめにする。残高アラートで毎秒の確認が必要になることはほとんどない。
* アラートには、`quota`、換算後の残高、`used_quota`、`request_count`、リクエスト時刻、HTTPステータスを含める。
* `Authorization` ヘッダー、`access_token`、その他の機密のアカウント情報は、ログに出力しない。

## 関連ドキュメント

* [残高照会APIのFAQ：文字化け、401エラー、AccessTokenとAPIキーの違い](https://docs.laozhang.ai/en/faq/balance-query-api.md)
* [残高があるのに失敗する理由](https://docs.laozhang.ai/ja/faq/balance-insufficient.md)
* [呼び出しログの見方と使い方](https://docs.laozhang.ai/en/faq/call-logs.md)
* [ログ照会API：呼び出し記録と課金額をコードからエクスポート](https://docs.laozhang.ai/ja/api-capabilities/log-query.md)
* [トークン管理API：APIキーの作成・無効化・削除をコードから](https://docs.laozhang.ai/ja/api-capabilities/token-management.md)
* [課金と料金](https://docs.laozhang.ai/ja/pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.