TokenLab Management APIにワークスペース残高照会機能が追加

残高不足によって自動化された本番パイプラインが停止する事態は防ぐことができます。TokenLab Management APIの残高照会機能を利用すれば、推論キーではなく管理トークンを使用して、自動化ワークフローから残高合計をクエリできるようになります。

本ガイドでは、GET /v1/management/balance エンドポイントの通信仕様、認証要件、通貨の取り扱い、および公式ドキュメントに照らし合わせてレスポンススキーマを直接確認する方法について解説します。

主なポイント

• Management APIの残高エンドポイント（GET /v1/management/balance）は、現在のワークスペース残高、チャージ総額、および累積利用額を返します。
• 認証には Dashboard → API → Management Tokens で作成した管理トークン（mt-...）が必要であり、運用チェック用のキーとモデル推論キー（sk-...）を分離できます。
• すべての金額はUSDで返されます。厳密な計算には、返却される小数文字列（balance_decimal、total_recharge_decimal、total_used_decimal）を使用してください。
• このエンドポイントは、/v1/management/api-keys/{keyId}/usage や /v1/management/api-keys/{keyId}/billing などのキー単位のレポート機能と組み合わせて使用できます。

管理トークンとモデル推論APIキーの違い

TokenLabにおいて、管理トークンとモデル推論キーは異なる運用上の役割を担っています:

• モデル推論APIキー（sk-...）: POST /v1/chat/completions、POST /v1/responses、POST /v1/messages によるネイティブAnthropic Messages、/v1beta/models/... によるGeminiなどの推論エンドポイントの呼び出しに使用されます。これらのキーは生成リクエストを実行しますが、組織レベルの財務データは公開しません。
• 管理トークン（mt-...）: /v1/management/* ルートに限定されています。モデル生成アクセス権を付与することなく、バックエンドがワークスペース残高の確認、APIキーの一覧取得・編集、使用状況の監視を行うことを可能にします。

これらの認証情報を分離することで、経理用スクリプトや財務監視ツールが課金対象となる推論呼び出しをトリガーできないようにし、同時にモデルワーカーがアカウント管理権限を取得できないように保護します。

残高エンドポイントの通信仕様

Authorization ヘッダーに管理トークンを指定して認証を行い、https://api.tokenlab.sh/v1/management/balance に GET リクエストを送信します:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

レスポンススキーマ

リクエストが成功すると、200 OK とともに organization_balance オブジェクトが返されます:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

レスポンスフィールド

• object (string): 常に organization_balance です。
• organization_id (string): 現在の管理トークンに関連付けられた組織。
• balance (number): 表示用の浮動小数点数で表された現在のワークスペース残高（USD）。
• balance_decimal (string): 財務照合用に小数文字列としてフォーマットされた、現在の正確なワークスペース残高（USD）。
• total_recharge (number): ワークスペースへのチャージ成功額の合計（USD）。
• total_recharge_decimal (string): 小数文字列としてフォーマットされた、ワークスペースへのチャージ成功額の正確な合計（USD）。
• total_used (number): ワークスペースの総利用額（USD）。
• total_used_decimal (string): 小数文字列としてフォーマットされた、ワークスペースの正確な総利用額（USD）。

金額フィールドは厳密にUSDです。しきい値チェックや元帳の照合のためにプログラムで残高をパースする際は、精度の低下を防ぐため、浮動小数点のプリミティブではなく任意精度小数ライブラリを使用して balance_decimal をパースしてください。

残高チェックの実装

一般的な統合パターンには以下のものがあります:

1. バッチ実行前のガードレール: gpt-5.5 や glm-5.2 などのモデルで大量の生成を行うような大規模ワークロードをディスパッチする前に、/v1/management/balance をクエリします。balance_decimal が推定バッチコストを下回る場合は、ジョブキューを一時停止します。
2. 残高低下アラート: 自動メール通知は Console → Settings で設定可能ですが、定期実行される監視cronでエンドポイントをポーリングし、社内のSlack、PagerDuty、またはWebhook通知をトリガーすることもできます。
3. 請求照合: リアルタイムのワークスペース残高と個別のキー利用履歴（/v1/management/api-keys/{keyId}/usage）を組み合わせることで、確定した請求明細項目とトークン消費支出を照合します。

エンドポイントの完全な仕様とキー管理方法については、ワークスペース残高取得 APIリファレンス および Management APIの概要 をご確認ください。