AI APIクレジットの自動チャージ：TokenLabの自動チャージ機能で残高不足を防ぐ方法

TokenLabの自動リチャージは、組織レベルの課金設定であり、残高が設定したしきい値を下回った際に自動的にクレジットを追加購入する機能です。正しく設定されていれば、エージェントループ、バッチジョブ、またはトラフィックの急増によって、残高不足で処理が強制停止される事態を防ぐことができます。本記事では、トリガーロジックの正確な仕組み、リチャージ中にカード決済が失敗した場合の挙動、実際の最小・最大金額、および課金ダッシュボードからこの機能を有効にする方法について詳しく解説します。

重要なポイント

• 自動リチャージはオプトイン方式であり、管理者またはオーナーが課金ダッシュボードから組織ごとに設定します。デフォルトでは有効になっていません。
• デフォルト設定は、トリガー金額が$5、復元金額が$30、月間リチャージ上限が$300です。リチャージ関連の最小金額は$1、月間上限は$10,000です。
• 決済が失敗した場合、TokenLabは自動的に再試行を行いません。自動リチャージを無効にし、トランザクションをpayment_failedまたはrequires_actionとしてマークし、失敗を知らせるメールを送信します。
• 現在、自動リチャージを設定・監視するための公開APIやWebhookはありません。設定はダッシュボードで行い、監視はダッシュボードのステータス、メール、トランザクション履歴を通じて行います。
• 自動リチャージを有効にするには、あらかじめStripeの支払い方法が保存されている必要があります。

TokenLabの自動リチャージを有効にする方法

1. 組織の管理者またはオーナーとしてサインインし、課金ダッシュボードを開きます。
2. まだ支払い方法を追加していない場合は追加します。保存されたStripeの支払い方法がないと、自動リチャージは有効にできません。
3. 「残高が下回ったとき（When balance drops below）」（トリガー金額）を設定します。これがトップアップを実行する残高基準となります。
4. 「残高を復元する（Restore balance to）」（復元金額）を設定します。これはトリガー金額よりも大きくする必要があります。リチャージ後に到達する残高です。
5. 月間リチャージ上限を設定するか、少なくとも1回のリチャージサイクルをカバーできる十分な余裕を持たせた状態で有効にします。
6. 保存して、自動リチャージが有効になっていることを確認します。ダッシュボードに現在のステータス（有効、一時停止、または無効）が表示されます。

これらのフィールドをカスタマイズしない場合、TokenLabはデフォルト値（トリガー$5、復元$30、月間上限$300）を適用します。これらのデフォルト値は、APIをテストする小規模なワークスペースには適していますが、本番環境のエージェントや顧客向けのチャットボットにはほぼ確実に少なすぎます。次に説明するモデルの組み合わせに合わせてサイズを調整してください。

モデル価格の概要：なぜリチャージ金額が重要なのか

TokenLabのカタログではトークンあたりのコストが大きく異なるため、適切なトリガー金額と復元金額は呼び出すモデルによって決まります。消費量に対して復元金額を低く設定しすぎると、前回のチャージが反映される前に再びトリガーに達してしまう可能性があります。

モデル	プロバイダー	入力 ($/MTok)	出力 ($/MTok)	コンテキストウィンドウ	ソース	観測日
Claude Sonnet 5	Anthropic	$2.00	$10.00	1,000,000	TokenLab ライブ価格スナップショット	2026-07-09
GPT-5.5	OpenAI	$5.00	$30.00	1,050,000	TokenLab ライブ価格スナップショット	2026-07-09
Gemini 3.5 Flash	Google	$1.50	$9.00	1,048,576	TokenLab ライブ価格スナップショット	2026-07-09
DeepSeek V4 Flash	DeepSeek	$0.09	$0.18	1,048,576	TokenLab ライブ価格スナップショット	2026-07-09
GLM-5.2	Z.ai	$0.70	$2.20	1,048,576	TokenLab ライブ価格スナップショット	2026-07-09

DeepSeek V4 Flashを主にドラフト作成に使用し、GPT-5.5を最終出力に使用するパイプラインは、すべてをGPT-5.5で実行する場合とは全く異なる速度でクレジットを消費します。低コストモデル中心の週に合わせて復元金額を設定していると、GPT-5.5を多用する週にはリチャージが頻繁に発生し、それぞれが月間上限にカウントされます。しきい値を固定する前に、実際の使用状況を確認してください。カタログ全体の料金比較については、料金比較ページを参照してください。

ワークスペースの設定を行う準備はできましたか？ 課金ダッシュボードを開き、上記のモデルの組み合わせに基づいてトリガー金額と復元金額を設定し、本番環境へのデプロイ前に支払い方法を確認してください。

トリガーロジックの実際の仕組み

自動リチャージは、固定タイマーで残高をポーリングするわけではありません。TokenLabは、決済が行われるたび残高をチェックし、設定されたトリガー金額と比較します。決済後の残高がトリガーを下回っていれば、リチャージが試行されます。

以下のいずれかに該当する場合、トリガーはスキップ（実行されない）されます：

• 現在の残高がすでにトリガー金額を上回っている。
• 組織に対する別の自動リチャージがすでに保留中である。
• トリガーロックが有効である（短期間に連続して決済が発生した際の重複リチャージを防ぐ）。
• アカウントに支払い方法が保存されていない。
• このリチャージを実行すると月間リチャージ上限を超えてしまう。

月間上限を超えてしまう場合、TokenLabは自動リチャージを一時停止し、lastFailureCode: "monthly_limit_reached"を記録します。これはバグではなく意図的な停止であり、実際の使用量に対して月間上限が低すぎる場合に、予期せぬ支出から保護するためのものです。このステータスが表示された場合は、月間上限を引き上げる（最大$10,000まで）か、上限に達した理由を確認した上で手動で再有効化してください。

リチャージが実行されると、TokenLabはUSDでStripeインボイスを作成し、保存された支払い方法に対して自動的に請求を行います。

自動リチャージ中にカード決済が拒否された場合はどうなるか？

これは、本番環境の稼働時間を自動リチャージに委ねるべきかどうかを判断する重要な質問であり、課金の実装はこれに明確に答えています。

決済が成功した場合： TokenLabは組織の残高を一度だけ加算し、トランザクションを完了としてマークし、利用可能な場合はインボイスまたは領収書のURLを保存し、月間支出合計を更新し、次回の自動リチャージを有効に維持し、決済成功メールを送信します。

決済が失敗した場合、または顧客の操作が必要な場合（例：3Dセキュア認証）：TokenLabはトランザクションを失敗としてマークし、自動リチャージを無効にし、ステータスをpayment_failedまたはrequires_actionに設定し、失敗の詳細を記録し、決済失敗メールを送信します。

最後のポイントは、再試行回数よりも重要です。TokenLabは拒否されたカードに対してサイレントな再試行を行わず、バックグラウンドで失敗しながら自動リチャージを有効のまま放置することもありません。機能自体がオフになり、その理由を知らせるメールが届きます。残高がゼロになればリクエストは停止しますが、自動リチャージが機能していると誤解したまま放置されることはありません。

運用面での意味合いは以下の通りです：

• 決済失敗メールは単なる通知ではなく、アクションが必要なアラートとして扱ってください。これは、支払い方法を修正してダッシュボードから再有効化するまで、自動リチャージがオフになっていることを意味します。
• 保存された支払い方法を最新の状態に保ってください。カードの有効期限切れがpayment_failed状態の最も一般的な原因であり、この実装ではセカンダリカードへの自動フォールバックはありません。
• 稼働時間が重要な場合は、メールだけに頼らないでください。メールを見逃したりフィルタリングされたりしても検出不能な停止にならないよう、独立した残高チェック（後述）を構築してください。

自動リチャージ用のAPIやWebhookはあるか？

現時点ではありません。自動リチャージの設定（トリガー金額、復元金額、月間上限、支払い方法）は、組織の管理者とオーナーのみがダッシュボードから行えます。これらのしきい値をプログラムで設定するための公開APIエンドポイントや、トリガー、成功、失敗イベントで発火する公開Webhookは文書化されていません。

現在存在する顧客向けの監視手段は以下の通りです：

• ダッシュボードステータス： 自動リチャージが有効か、一時停止中か、無効かを表示し、該当する場合は最後の失敗コードを表示します。
• メール通知： 残高不足の警告および決済の成功/失敗メール。
• トランザクション履歴： 各リチャージ試行の記録、結果、および利用可能な場合のインボイス/領収書リンク。

本番システムでプログラムによる監視が必要な場合、現在の実用的な回避策は、ダッシュボードセッションが提供する認証済み読み取りアクセスを通じて組織の残高をチェックするスケジュールジョブを作成し、自動リチャージのトリガーよりも低いしきい値を下回った場合にチームにアラートを送ることです。これにより、カード失敗後に自動リチャージ自体が無効になった場合でも、独立したシグナルを得ることができます。想定されるエンドポイントやペイロード形式に対して統合コードを構築しないでください。TokenLabが課金APIやWebhookを文書化した場合は、アラートパイプラインに組み込む前にAPIリファレンスで正確な仕様を確認してください。

最小、最大、およびデフォルト金額

フィールド	最小	最大	デフォルト	備考
トリガー金額（「残高が下回ったとき」）	$1	復元金額未満	$5	復元金額より低く維持する必要がある
復元金額（「残高を復元する」）	$1	月間上限による制限	$30	トリガー金額より高くする必要がある
月間リチャージ上限	1回のリチャージサイクルをカバー	$10,000	$300	上限に達するとmonthly_limit_reachedでリチャージが停止

ソース：TokenLab課金ダッシュボードおよび自動リチャージ実装、https://tokenlab.sh/en/dashboard/billing、2026-07-09観測。

バーストのリスクがある本番ワークロードを実行している場合、$300のデフォルト月間上限は保守的すぎることがよくあります。画像や動画生成の午後、またはエージェントのツール呼び出しが忙しい1日は、その上限にすぐに近づく可能性があります。作業中に停止してからではなく、モデルの組み合わせと典型的な日次支出を推定した上で、意図的に引き上げてください。

誰がこれを有効にすべきか

自動リチャージはすべてのワークスペースに必要なわけではありません。使用量が少なく予測可能であれば、手動のトップアップで十分です。以下に該当する場合は設定する価値があります：

• 自律型または半自律型エージェント： Claude Sonnet 5やKimi K2.7 Codeのようなモデルで実行されるエージェントループはクレジットを不均一に消費する可能性があり、スタックしたループは人間が気づくよりも早く残高を使い果たします。
• 顧客向けチャットボット： サポートや製品のチャットボットは、自社製品の使用量に応じてトラフィックが拡大します。週末の急増が月曜日の停止にならないようにすべきです。
• バースト的に実行される生成ワークロード： 画像や動画のジョブ（Nano Banana Pro、Seedance、Veo 3）はローンチやコンテンツバッチの際に集中し、1回のレンダリングセッションで典型的な1週間分以上の支出になることがあります。
• スケジュールされたバッチジョブ： 夜間や週次のパイプラインは、実行中の残高不足が診断や再実行にコストがかかる典型的なケースです。

設定チェックリスト

ステップ	確認事項	重要性
支払い方法が最新か確認	カードの有効期限切れがないか、ダッシュボードで確認	有効な支払い方法がないとリチャージは実行不可
トリガー金額をピーク時の日次消費量以上に設定	平均ではなく、最も忙しい日を基準にする	低すぎると、急増時にトップアップが間に合わず残高が枯渇する
復元金額を週次支出以上に設定	上記のモデル価格表を使用して推定	GPT-5.5を多用する週はDeepSeek V4 Flashを多用する週よりはるかに高額
月間上限に十分な余裕を持たせる	デフォルトの$300は本番環境には低すぎることが多い	上限に達するとmonthly_limit_reachedで自動リチャージが停止
失敗メールをアラートとして扱う	決済失敗メールをオンコールチャネルにルーティング	失敗時に自動リチャージは自己無効化されるため、他の手段では通知されない
独立した残高監視を追加	自動リチャージのトリガーとは別にスケジュールで残高をポーリング	公開Webhookはまだ存在しないため、ダッシュボードのみの可視性に頼らない
使用状況を毎週レビュー	モデル別およびプロジェクト別の消費量を確認	自動リチャージは停止リスクを取り除くが、コストの可視性を代替するものではない

しきい値を決定するためのモデルコスト比較については料金比較ページを、重要でない呼び出しをDeepSeek V4 FlashやGemini 3.5 Flashのような安価なモデルに切り替える方法についてはモデルランキングページを参照してください。

自動リチャージはセーフティネットであり、白紙委任ではない

自動リチャージは「ワークロードの途中でクレジットがなくなる」という特定の失敗モードを解決します。予算を管理するものではなく、月間上限が存在するのはまさにそのためです。この機能を最大限に活用するチームは、現実的な復元金額と実際の使用量を反映した月間上限を組み合わせ、失敗メールを無視されがちな共有受信トレイではなく、人間が確実に確認できる場所にルーティングしています。

制限事項と考慮事項

• 手数料構造： 自動リチャージのインボイスにクレジット金額以外の処理手数料が含まれるかどうかは、TokenLabの公開課金ドキュメントでは確認されていません。Stripeのインボイス明細または利用規約を直接確認してください。
• 処理レイテンシ： トリガーされたリチャージから新しい残高がアカウントに反映されるまでの時間は、ここではベンチマークされていません。ワークロードに厳しい期限がある場合は、まず手動トップアップでテストし、時間のかかる急増に対して自動リチャージを信頼する前にダッシュボードのタイミングを観察してください。
• プログラムによるアクセス： 自動リチャージの設定やイベントのための公開APIやWebhookは現在文書化されていません。TokenLabが追加した場合は、それに基づいて構築する前に公式APIリファレンスで正確なエンドポイントとペイロードを確認してください。

FAQ

TokenLabの自動リチャージしきい値を設定するAPIはありますか？ 現時点ではありません。自動リチャージは組織の管理者またはオーナーが課金ダッシュボードから設定します。トリガー、復元、または月間上限値をプログラムで設定するための公開APIエンドポイントは文書化されていません。

自動リチャージの最小・最大金額はいくらですか？ トリガー、復元、および関連金額の最小値は$1です。月間リチャージ上限の最大値は$10,000です。デフォルトはトリガー$5、復元$30、月間上限$300です。

自動リチャージの請求中にカードが拒否されたらどうなりますか？ TokenLabはトランザクションを失敗としてマークし、自動リチャージを無効にし、ステータスをpayment_failedまたはrequires_actionに設定し、失敗の詳細を記録し、決済失敗メールを送信します。サイレントな再試行は行いません。

決済失敗後、自動リチャージは自動的に再試行しますか？ 現在の実装には自動再試行は組み込まれていません。代わりに、機能自体が無効になり、メールで通知されるため、支払い方法を修正して手動で再有効化する必要があります。

自動リチャージはデフォルトでオンになっていますか？ いいえ。組織ごとのオプトイン方式であり、有効にするには保存された支払い方法が必要です。

自動リチャージは月間支出上限の代わりになりますか？ いいえ。月間リチャージ上限は自動リチャージ自体が月間に支出できる額を制限するものですが、これは稼働時間のためのセーフティネットであり、予算管理ツールではありません。使用状況は別途レビューしてください。

課金ダッシュボードから自動リチャージを設定するか、まずモデルページでモデル価格を比較して、しきい値を正しく設定してください。