AI API 請求元帳の構築: すべてのモデル呼び出しの見積、予約、決済、調整
マルチモデル ゲートウェイの実用的な請求管理パターン: リクエスト前のコストの見積もり、テナントの予算の確保、プロバイダーの使用量の正規化、実際の料金の決済、およびプロバイダーの生の応答だけに依存せずに請求書を調整します。
顧客向けの AI API 請求は、プロバイダーの未加工の使用状況を毎月エクスポートすることはできません。ゲートウェイが複数のモデルをテナント、チーム、またはパートナーに公開する場合、請求書が存在する前に、請求担当者はより難しい質問に答える必要があります。つまり、このリクエストは今すぐ許可されるべきでしょうか?その費用は後でどのように説明されますか?
実際のパターンは、見積もり、予約、決済、調整の 4 つの段階からなる請求元帳です。リクエストの前に、予想される費用を見積もってください。許容される最悪のケースに対応できる十分なテナント予算を確保してください。使用量が判明してから実費を精算してください。ゲートウェイ台帳をプロバイダー側の記録と照合して、請求書が防御可能な状態を維持できるようにします。
この記事では、マルチモデル API ゲートウェイの制御ループについて説明します。これは、ゲートウェイが社内チーム、前払い顧客、代理店クライアント、下流パートナーのいずれに請求する場合にも役立ちます。
請求の問題: プロバイダーの使用量は顧客の請求書ではありません
事実: 主要な AI プロバイダーは、1 つのユニバーサル トークン カウンターや 1 つのユニバーサル価格を公開していません。 OpenAI は、個別の入力トークン レート、キャッシュされた入力トークン レート、および出力トークン レートを使用してモデルごとの価格を公開します。 OpenAI プロンプト キャッシュは、キャッシュされたトークンの使用状況を API 応答使用状況フィールドに報告します。 Anthropic は、通常の入力トークン、キャッシュ作成入力トークン、キャッシュ読み取り入力トークン、および出力トークンの個別のカウンターを文書化します。 Gemini 価格設定では、入力、出力、およびオーディオ トークンなどのモダリティ固有の使用法を含むその他のトークン カテゴリが区別されます。
つまり、ゲートウェイは total_tokens に 1 つの価格を掛けて安全に請求することはできません。プロバイダーに依存しない課金スキーマの背後にプロバイダー固有のアダプターが必要です。
次のような状況では、問題がより顕著になります:
- プリペイド クレジット: ゲートウェイは、テナントの支出がゼロ未満になる前にリクエストを拒否する必要があります。
- パートナー マークアップ: パートナーにはプロバイダ請求書のコピーではなく、顧客向けの独自の請求書が必要です。
- ストリーミング: 最終的なトークンの使用量が判明する前に応答が開始されます。
- プロンプト キャッシュ: キャッシュされた入力はキャッシュされていない入力よりも安くなる可能性がありますが、これは個別に測定した場合に限ります。
- 推論とツールの使用: 一部のモデルは、追加の使用ディメンション、非表示の出力クラス、またはメディア ユニットを公開します。
- プロバイダ料金の変更: 料金表が変更された後も、先月の請求書を再現できる必要があります。
推奨事項: 請求をリクエスト ログに対するダッシュボード クエリとしてではなく、追加専用の財務台帳として扱います。
コア アーキテクチャ
信頼できる課金アーキテクチャには 6 つのコンポーネントがあります:
- テナント アカウント: 顧客、ワークスペース、再販業者クライアント、または内部コスト センター。
- 料金表サービス: プロバイダー、モデル、請求クラス、通貨、およびマークアップ ルールのバージョン化された価格。
- Estimator: は、リクエスト パラメーターとモデル ポリシーからプリフライト見積もりを計算します。
- 予約台帳: には、プロバイダーの通話が開始される前の予算が保持されます。
- 使用状況ノーマライザー: プロバイダ固有の使用状況フィールドを内部の請求単位に変換します。
- 決済および調整ジョブ: 料金を確定し、プロバイダー側の記録と比較します。
制御フローは次のようになります:
client request
-> authenticate tenant and key
-> select model and rate-card version
-> estimate input and max output cost
-> reserve tenant balance
-> call provider
-> normalize returned usage
-> settle actual cost
-> release unused reservation
-> emit invoice-ready ledger event重要な設計上の選択は、リクエストが単に観察されるだけではないということです。実行前と実行後は財務的に管理されます。
ステップ 1: プロバイダーが電話をかける前に見積もりを行う
プリフライト見積もりは、予算を強制できるほど悲観的であると同時に、顧客やパートナーに提示できるほど説明可能なものである必要があります。
通常、入力には次のものが含まれます:
- テナント ID と料金プラン;
- API キー ID またはプロジェクト ID;
- ルーティング ルール適用後のプロバイダーとモデル ID;
- キャッシュされていない入力トークンの推定数;
- 既知のキャッシュ入力適格性 (利用可能な場合);
max_tokens、max_output_tokens、または同等の出力上限;- ツール、画像、音声、またはその他のモダリティ パラメータ;
- パートナーのマークアップ、割引、または再販業者の価格設定ルール;
- 通貨と丸めポリシー。
テキスト生成のための単純な引用式は次のようになります:
estimated_cost =
estimated_uncached_input_tokens * input_rate
+ estimated_cached_input_tokens * cached_input_rate
+ max_output_tokens * output_rate
+ request_fee
+ partner_markup推奨事項: 最終出力の長さが不明な場合は、設定された最大出力に対して予約してください。アプリケーションが出力上限を無制限のままにする場合、ゲートウェイはテナントまたはモデルのデフォルトを適用する必要があります。最大責任が存在しない場合、予算の執行は決定論的ではありません。
これにより、実際にはコストがかからなかった一部のリクエストが拒否される可能性があります。それがトレードオフです。プリペイド システムの場合、より安全なデフォルトは、決済後に未使用資金が解放される悲観的な予約です。請求書が発行される企業顧客の場合、チームはソフト超過を許可し、主にアラートに見積を使用する場合があります。
ステップ 2: テナントの予算を予約する
予約により、テナント アカウントが許可された残高を超えて使用することがなくなります。これはアトミックである必要があります。予約が成功してプロバイダー呼び出しが開始されるか、プロバイダーのコストが発生する前にリクエストが拒否されるかのどちらかです。
予約レコードには次のものが含まれる場合があります:
{
"reservation_id": "res_01J...",
"tenant_id": "tenant_123",
"api_key_id": "key_456",
"request_id": "req_789",
"provider": "example_provider",
"model": "model-a",
"rate_card_version": "2026-08-01",
"quoted_amount": "0.032100",
"currency": "USD",
"status": "reserved",
"expires_at": "2026-08-11T12:05:00Z"
}ネットワーク障害やクライアントの切断に備えて、短い予約有効期限を使用します。クリーンアップ ジョブでは、決済に達しなかった期限切れの予約を解放する必要があります。ただし、クライアントが切断されたという理由だけで予約を解放しないでください。プロバイダーの呼び出しはまだ完了しており、コストが発生する可能性があります。プロバイダーのリクエスト状態を個別に追跡します。
推奨事項: リクエスト ID または冪等キーによって予約を冪等にします。クライアント、ゲートウェイ、またはワーカーからの再試行では、同じ論理リクエストに対して複数の予算保留を作成しないでください。
ステップ 3: プロバイダーの使用状況を正規化する
プロバイダーの応答は、小さな内部スキーマに変換する必要があります。プロバイダーが新しい使用法フィールドを追加しても、安定した状態を保ちます。
実用的な正規化された使用スキーマ:
{
"input_uncached_tokens": 1200,
"input_cached_tokens": 800,
"cache_write_tokens": 0,
"output_tokens": 650,
"reasoning_or_hidden_output_tokens": 0,
"tool_or_media_units": [],
"request_fee_units": 1,
"provider_request_id": "prov_abc",
"usage_source": "provider_response",
"is_estimated": false
}このスキーマは、意図的にどのプロバイダの応答とも同一ではありません。プロバイダー固有の単位のエスケープハッチを維持しながら、請求書に必要な請求の寸法を取得します。
キャッシュされたトークンには独自の行が必要です
事実: プロンプト キャッシュの価格は、キャッシュされていない入力とは異なる場合があります。キャッシュされたトークンが合計入力トークンにマージされると、顧客に過剰に請求されるか、ゲートウェイがプロバイダーのコストを過小評価する可能性があります。キャッシュされた入力は、元帳と請求書の両方で独自の請求クラスとして表示される必要があります。
キャッシュの書き込みとキャッシュの読み取りは常に同じであるとは限りません
一部のプロバイダは、キャッシュ エントリの作成とキャッシュからの読み取りを区別します。ノーマライザーは、キャッシュされた入力が常に 1 つの請求レートを意味すると想定すべきではありません。プロバイダーにキャッシュ書き込みトークンとキャッシュ読み取りトークンがある場合は、それらを個別にマッピングするか、プロバイダー固有のサブユニットとして保持します。
推論と非表示の出力にはポリシーが必要です
一部のモデルは、推論関連の使用法や非表示の出力カウンターを公開します。プロバイダーがこれらのユニットに対して請求を行う場合、ゲートウェイはユニットを直接表示するか、出力カテゴリにロールするか、または別の請求明細行としてリストするかを決定する必要があります。
推奨事項: 顧客向けの請求書には平易な言葉を使用する必要があります。たとえば、「出力トークンの推論」は、生のプロバイダー フィールド名よりも明確です。生のフィールドを監査に利用できるようにしておきますが、すべての顧客にプロバイダーの内部構造を理解することを強制しないでください。
ステップ 4: 実際の費用を決済する
決済により、正規化された使用量が最終的な台帳エントリに変換されます。これは追加専用であり、リクエストに使用された料金表のバージョンを参照する必要があります。
解決されたイベントは次のようになります:
{
"ledger_event_id": "led_01J...",
"event_type": "settlement",
"tenant_id": "tenant_123",
"request_id": "req_789",
"reservation_id": "res_01J...",
"provider": "example_provider",
"model": "model-a",
"rate_card_version": "2026-08-01",
"lines": [
{
"billing_class": "input_uncached_tokens",
"quantity": 1200,
"unit": "token",
"unit_price": "0.00000250",
"amount": "0.003000"
},
{
"billing_class": "input_cached_tokens",
"quantity": 800,
"unit": "token",
"unit_price": "0.00000125",
"amount": "0.001000"
},
{
"billing_class": "output_tokens",
"quantity": 650,
"unit": "token",
"unit_price": "0.00001000",
"amount": "0.006500"
}
],
"total_amount": "0.010500",
"currency": "USD",
"status": "settled"
}リクエストが 0.032100 に予約され、0.010500 で決済された場合、台帳は 0.021600 を解放して利用可能な残高に戻します。
推奨事項: 現在の価格表から古い請求書明細を再計算しないでください。不変の料金表バージョンを保存し、すべての見積、予約、決済イベントにバージョン ID を添付します。そうしないと、プロバイダーがモデルの価格を更新した後、請求書を再現できなくなる可能性があります。
ストリーミング リクエスト: 最初に予約し、後で決済します
ストリーミングでは、ゲートウェイが最終的な使用量を認識する前にユーザーが出力の受信を開始するため、請求が複雑になります。答えは、プリフライト チェックをスキップしないことです。ゲートウェイはストリームを開く前に予約する必要があります。
このワークフローを使用します:
- 入力トークンと最大出力コストを見積もります。
- テナントの予算を予約します。
- プロバイダー ストリームを開きます。
- チャンクをクライアントに転送します。
- プロバイダーが送信したとき、またはフォローアップの使用状況記録が利用可能なときに、最終的な使用状況を取得します。
- 実際の費用を決済し、未使用の予約を解放します。
最終的な使用量が利用できない場合は、和解金が正確であるかのように振る舞うのではなく、見積もられたものとしてマークしてください:
"usage_source": "gateway_estimate",
"is_estimated": true,
"reconciliation_status": "pending"推奨事項: 毎日の調整では、推定ストリーミング イベント、失敗したリクエスト、タイムアウト、および再試行を優先する必要があります。これらは、ゲートウェイの記録とプロバイダーの請求書の間に差異が生じる可能性が最も高い領域です。
料金表のバージョン管理とマークアップ ルール
料金表は、変更可能なスプレッドシートではなく、バージョン管理されたオブジェクトである必要があります。
最小フィールド:
- プロバイダー;
- モデルID;
- 請求クラス;
- ユニット (トークン、リクエスト、画像、音声秒、ツール ユニットなど);
- 単価;
- 通貨;
- 有効な開始および終了タイムスタンプ;
- 丸めポリシー;
- テナント プランまたはパートナー マークアップ ルール;
- ソース参照と承認メタデータ。
マークアップ ルールは明示的である必要があります。例:
- 追加料金: プロバイダ料金に 20% が追加されます。
- 固定小売: テナントは、プロバイダーの価格に関係なく、固定のトークン価格を支払います。
- 段階的: 最初は 1,000 万トークンを 1 つのレートで、その後はより低いレートで。
- 含まれるクレジット: 使用すると、超過料金の請求が開始される前に毎月の許容量が消費されます。
トレードオフ: 料金表のバージョニングにより運用作業が増えますが、請求書の紛争が考古学的な問題になるのを防ぎます。カスタマー サポート エージェントは、今日のプロバイダーの価格を確認せずに、8 月 3 日のリクエストが特定の料金で請求された理由を説明できる必要があります。
分析から請求元帳を分離する
分析と課金には異なる許容範囲があります。分析は、集約、遅延、サンプリング、または修正できます。請求は完全で、冪等で、監査可能で、説明可能である必要があります。
次のような質問には分析を使用します:
- 最も多くのトークンを使用しているのはどのチームですか?
- 最も急速に成長しているモデルはどれですか?
- プロンプト キャッシュによってコストが削減できるのはどこですか?
- 異常に高価なリクエストを生成するキーはどれですか?
次のような質問には請求元帳を使用します:
- このリクエストはテナントの残高に対して承認されましたか?
- この請求が発生した料金表のバージョンはどれですか?
- 未使用の予約は解放されましたか?
- 顧客の請求書は決済済みの使用量と一致していますか?
- ゲートウェイの使用法はプロバイダー側の使用法と一致しますか?
事実: OpenTelemetry GenAI のセマンティック規則には、入力トークンや出力トークンなどのトークン使用属性が含まれます。これは、可観測性とトレースをコスト イベントに結合するのに役立ちます。ただし、テレメトリ属性は料金表、予約、決済、四捨五入、請求書の状態の代わりにはなりません。
毎日の調整ワークフロー
調整では、ゲートウェイの決済済み台帳とプロバイダー側の使用状況が比較されます。目標は、すべての中間フィールドで完全に一致することではありません。目標は、材料の差異を早期に検出して、請求書、料金表、アダプターを修正することです。
実際的な日常の仕事:
- プロバイダー、モデル、テナントまたは API キー、請求クラス、UTC 日別にゲートウェイ台帳イベントをグループ化します。
- キー ID、モデル、日など、利用可能なディメンションごとにグループ化されたプロバイダー側の使用状況を取得します。API
- 可能な場合、リクエスト応答に使用されるのと同じアダプター コードを通じてプロバイダーのエクスポートを正規化します。
- 請求クラスごとに数量とコストを比較します。
- 0.5% の数量差や絶対コストの大きな差など、しきい値を超える差異にフラグを立てます。
- 差異の原因を分類します: ストリーミング推定、再試行、失敗したリクエスト、キャッシュ アカウンティング、モデル エイリアスの変更、プロバイダー レコードの遅延、またはリクエスト ID の欠落。
- 古い決済イベントを編集する代わりに、調整イベントを作成します。
推奨事項: 調整が簡素化されるため、運用上可能な場合はテナントごとにプロバイダ API キーを使用します。これによりキー管理のオーバーヘッドが大きくなりすぎる場合は、サポートされている場合は内部テナント ID をプロバイダー メタデータにマッピングし、信頼性の高いリクエスト ID ブリッジを維持します。
顧客が理解できる請求書明細
顧客向けの請求書にはプロバイダー JSON を反映しないでください。安定したビジネス条件で法案を説明する必要があります。
便利な請求書の列:
- 期間;
- テナント、プロジェクト、または API キーラベル;
- モデルまたはモデル プロファイル;
- リクエスト数;
- キャッシュされていない入力トークン;
- キャッシュされた入力トークン;
- 出力トークン;
- メディアまたはツールユニット (該当する場合);
- 割引、クレジット、または値上げ;
- 合計金額と通貨。
パートナーの場合は、ビジネス モデルで必要な場合にのみ、卸売コストと小売料金の両方を含めます。多くの再販業者の請求書には小売使用量のみが表示されますが、パートナー ダッシュボードにはマージンが個別に表示される場合があります。
トレードオフ: 統合された請求書スキーマにより読みやすさが向上しますが、プロバイダー固有の請求詳細には依然としてエスケープハッチが必要です。デフォルトでは請求書明細行をシンプルにし、詳細な監査フィールドを必要とする上級顧客向けにエクスポートを提供します。
実装チェックリスト
発売前
- サポートされているすべてのプロバイダーに対して正規化された請求クラスを定義します。
- 発効日を含む不変の料金表バージョンを作成します。
- 出力上限を要求するか、ゲートウェイのデフォルトを適用します。
- 冪等キーを使用してアトミック予約を実装します。
- 通貨ごとに丸めルールを設定します。
- キャッシュされたトークン、推論トークン、メディア ユニット、リクエスト料金の請求方法を決定します。
- 再試行、タイムアウト、クライアントの切断、プロバイダーのエラーをテストします。
- 解決されたイベントを編集する代わりに、調整イベントのメカニズムを構築します。
リクエスト処理中
- テナントとキーを認証します。
- ルーティングとフォールバック ポリシーの後に最終モデルを解決します。
- 正しい料金表のバージョンを選択してください。
- 最悪の場合のコストを見積もります。
- 残高を予約するか、リクエストを拒否します。
- 利用可能な場合はプロバイダー リクエスト ID を記録します。
- レスポンスからの使用法を正規化します。
- 未使用の予約を決済、解放し、請求書発行可能イベントを発行します。
リクエスト処理後
- プロバイダー、キー、モデル、請求クラス、日ごとに毎日調整を実行します。
- 推定ストリーミング決済額を確認します。
- 料金表エントリが欠落しているモデルの使用状況にフラグを立てます。
- キャッシュされたトークン アカウンティングによって生じる差異を監視します。
- 最終的な請求の前に顧客請求書のプレビューを生成します。
計画すべき予測
予測: AI API の請求は、減少するのではなく、より多次元になるでしょう。トークン クラス、キャッシュ クラス、メディア ユニット、ツール実行、および推論関連のカウンターは、モデルの機能が変化するにつれて拡張し続ける可能性があります。
予測: 顧客は、リクエスト、キー、プロジェクト、請求書のレベルで使用方法の説明を期待するでしょう。 API アクセスを再販したり、前払い予算を適用したりするチームにとって、追跡可能な項目がなければ月ごとの合計では不十分です。
予測: すでに見積り、予約、決済、調整を分離しているゲートウェイは、請求書システム全体を書き換えることなく請求クラスを追加できるため、新しい価格モデルに迅速に適応できるようになります。
実用的な結論
1 つのゲートウェイを介して複数の AI プロバイダーを公開する場合は、請求に関する紛争により問題が発生する前に請求台帳を作成してください。 4 つの保証から始めます:
- すべての請求可能なリクエストはプリフライト見積もりを受け取ります。
- すべてのプリペイド テナントまたは上限付きテナントには、プロバイダーの通話が開始される前に予算が予約されています。
- すべてのプロバイダーの応答は、安定した請求クラスに正規化されます。
- すべての請求書は、プロバイダー側の使用量と、その時点で使用されている正確な料金表のバージョンと照合できます。
この制御ループにより、統合 AI API 請求が顧客にとってわかりやすくなり、プリペイド クレジットに対して適用可能になり、パートナー マークアップに対して柔軟になり、プロバイダの価格設定や使用形式が変更された場合に監査可能になります。