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

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

AccessTokenは、モデルのリクエストに使うAPIキーとは別のもので、アカウントに対してより広い権限を持ちます。

サーバー内の環境変数かシークレット管理ツールに保管してください。
ブラウザやクライアントアプリには含めないでください。

AccessTokenの取得

アカウント設定を開く

コンソールにログインし、アカウント設定を開きます。

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

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

AccessTokenをコピーする

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

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

エンドポイント

GET https://api.laozhang.ai/api/user/self
Authorization: <your AccessToken>

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

レスポンス

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

{
  "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を一度だけ設定します。

export LAOZHANG_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

cURL
cURL with jq
Python
Node.js

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 を報告したりすることがあります。

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
  }'

python -m pip install requests で requests をインストールしてから実行してください。

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で圧縮されたレスポンスを自動的に展開します。

このコードを .mjs ファイルに保存し、Node.js 18以降で実行してください。

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

{
  "success": false,
  "message": "Unauthorized"
}

Authorization ヘッダーが空、AccessTokenが不完全または無効になっている、あるいはAccessTokenではなくモデル用のAPIキーを送っている場合に発生します。原因ごとの対処は、残高照会APIで401が返るときの対処にまとめています。ステータスコードとレスポンスボディは、組み合わせて判断してください。

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

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

403 Forbidden

{
  "success": false,
  "message": "Forbidden"
}

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

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

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

残高の監視

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

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以外のときに通知を送ります。例：

*/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

動画生成API

テキストAPI

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

AccessTokenの取得

エンドポイント

レスポンス

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

コード例

エラー

401 Unauthorized

403 Forbidden

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

残高の監視

関連ドキュメント

​AccessTokenの取得

​エンドポイント

​レスポンス

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

​コード例

​エラー

​401 Unauthorized

​403 Forbidden

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

​残高の監視

​関連ドキュメント

AccessTokenの取得

エンドポイント

レスポンス

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

コード例

エラー

401 Unauthorized

403 Forbidden

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

残高の監視

関連ドキュメント