メインコンテンツへスキップ

API概要

Balance Query API は、合計クォータ、使用済みクォータ、残高、リクエスト数を含む、アカウントの現在のクォータ使用状況を取得します。 この API を使うと、アカウントの残高を簡単に監視でき、事前かつ柔軟な残高アラート管理が可能になります。

Authorization token の取得方法

この API はパーソナルアクセス token(nap_で始まる形式)で認証します。モデルの呼び出しに使用する API Key とは異なります。
1

パーソナルアクセス tokens を開く

api.apiyi.com/account/profile のプロフィールページにアクセスします。アカウントオプションで、パーソナルアクセス tokens → token を作成をクリックします。
2

権限を選択する

この API に必要な権限は プロフィール · 読み取り のみです。デフォルトの有効期限は30日間ですので、より長い期間を選択することをおすすめします。
3

token を保存する

token が作成されたらすぐにコピーし、Authorization ヘッダーに設定します。
パーソナルアクセス token の作成:名前、有効期限、IP 許可リスト、権限
旧来のシステム tokens は 2026-11-11 (UTC+8) に廃止される予定です。「アカウントオプション - システム token」で生成された AccessTokens は、その期日まで引き続き機能します。その期日以降は 401 ACCESS_TOKEN_LEGACY_RETIRED を返します。 利用状況を確認した上で期日を延長する可能性もありますが、今すぐパーソナルアクセス token への切り替えをおすすめします。ヘッダーの値を置き換えるだけで、コードを変更する必要はありません。 有効期限、IP 許可リスト、権限の詳細については、パーソナルアクセス token とは? を参照してください。

API 情報

リクエスト詳細

リクエストヘッダー

リクエストパラメータ

これはGETリクエストのため、リクエストボディパラメータは不要です。

レスポンス詳細

成功レスポンス例

主なレスポンスフィールド

クォータ換算

換算ルール

500,000 quota = $1.00 USD
計算式:
  • USD 金額 = quota ÷ 500,000
  • 残りクォータ = quota(quota は現在の残高を表します)
  • 残り USD = quota ÷ 500,000
例:
  • quota: 24997909 → $49.99 USD(現在の残高)
  • used_quota: 10027091 → $20.05 USD(使用額)

エラーレスポンス

HTTP 401 - 認証失敗

原因: token が無効であるか、有効期限切れ、または削除されています。アカウントのパスワード、2要素認証、またはパスキーを変更すると、すべてのパーソナルアクセス token が無効化されます。 解決策: コンソールで新しいパーソナルアクセス token を作成してください。 他の2つの401レスポンスには、明示的なメッセージが含まれています:

HTTP 403 - 権限拒否

原因: パーソナルアクセス token に Profile · Read がありません。 解決策: その権限を持つ新しい token を作成してください。権限は作成後に変更できません。

コード例

cURLの例

重要: APIはgzip圧縮されたコンテンツを返すため、--compressedオプションが必須です。指定しない場合、文字化けした出力が返されます。
クイックテスト(YOUR_TOKEN_HEREを置き換えてください):
注意:-sオプションはプログレスバーを非表示にし、--compressedはgzipレスポンスを自動的に解凍します

Pythonの例(基本)

Pythonの例(最適化版)

基本の例に加えて、以下の機能を追加しています:

エラーハンドリング

完全な例外処理とエラー捕捉

環境変数

安全なtoken管理、ハードコードの回避

フォーマット済み出力

見やすいテーブル表示と数値フォーマット

自動変換

USD金額の自動計算
以下のコードをquota.pyとして保存すれば、すぐに実行できます:
使用方法:
出力例:

よくある質問

上記の「Authorization tokenの取得方法」の手順に従ってください。プロフィールページでパーソナルアクセストークンを作成し、「Profile · Read」を選択します。従来のシステムtokenは2026-11-11 (UTC+8)に廃止される予定です。パーソナルアクセストークンとは何ですか?をご覧ください。
いいえ、残高照会APIはクォータを消費しません。
レート制限の発生を避けるため、照会間隔は少なくとも1秒以上空けることを推奨します。
このフィールドは各種AIモデルの価格情報を返します。残高情報のみが必要な場合は、無視して問題ありません。
quotaフィールドは現在の残高を表しています。quotaが0または0に近い場合、アカウントの残高が不足しているためチャージが必要です。
問題: curlを実行すると文字化けしたテキストが返される、またはjqが「Invalid numeric literal」とエラーを報告する原因: APIがgzip圧縮されたコンテンツ(Content-Encoding: gzip)を返しますが、curlが自動的に展開しないためです。解決策: curlが自動的に展開するように、--compressedオプションを追加してください:

重要な注意事項

セキュリティに関する注意
  • Authorization token をコードにハードコードしないでください
  • 機密情報の管理には環境変数または設定ファイルを使用してください
  • token を含むコードを公開リポジトリにコミットしないでください
リクエスト制限
  • 適切なリクエストタイムアウトを設定してください(推奨: 10秒)
  • 過度に頻繁なクエリリクエストは避けてください

エラーハンドリングの推奨事項

  • ネットワーク例外、タイムアウト、認証失敗は必ず処理してください
  • トラブルシューティングをしやすくするため、エラーをログに記録してください

レスポンス形式に関する注意

  • API は gzip 圧縮されたコンテンツを返します。curl では--compressedオプションが必要です
  • Python の requests ライブラリは、追加設定なしで gzip の解凍を自動的に処理します