AI API ゲートウェイのバージョン化された価格カタログ: 見積価格の変動とチャージバックによる価格ドリフトを阻止
プロバイダーの価格カードは、モデル、トークン カテゴリ、キャッシュ動作、ツールの使用状況、デプロイメント タイプ、リージョン、および認定容量プランによって異なります。ゲートウェイには、見積書、予約、台帳、予算、チャージバックが価格変動時に説明可能な状態を維持できるように、バージョン化された価格カタログが必要です。
ゲートウェイがプロバイダーの価格設定を静的なルックアップ テーブルとして扱う場合、AI API の請求は失敗します。難しいのは、トークンにレートを掛けることではありません。難しいのは、リクエスト時にどのレートが有効であったか、どの SKU が実際の使用量バケットと一致したか、価格が承認されたかどうか、顧客の見積もりがプロバイダの請求書と異なる理由を把握することです。
複数のモデル、アカウント、リージョン、キャッシュ モード、バッチ ジョブ、ホストされたツール、プロビジョニングされた展開をサポートするゲートウェイには、価格設定コントロール プレーンが必要です。そのコントロール プレーンは、プロバイダーのプライスカードを取り込み、承認された料金をすべてバージョン管理し、プロバイダーの使用状況を請求可能な SKU にマッピングし、展開前に見積もりをテストし、決済された台帳の行を請求書と照合する必要があります。
読者の問題: 価格ドリフトは価格設定ページ以上に影響を及ぼします
プロバイダーの価格は、モデル バージョン、入力トークン、キャッシュされた入力トークン、出力トークン、推論トークン、キャッシュ書き込み、ホストされたツール、バッチ割引、デプロイメント タイプ、リージョン、通貨、認定容量プランなど、アプリケーション チームが直接見ることはほとんどない要素によって異なる場合があります。これらのディメンションが 1 つの「トークンあたりのコスト」フィールドにフラット化されると、ゲートウェイは最終的に見積もりを誤ったり、予算を過剰に予約したり、テナントに請求額を下回ったり、間違ったコスト センターに支出を割り当てたりすることになります。
障害は通常、次の 5 つの場所のいずれかで発生します。
- プリフライト見積もり: ゲートウェイが古いレートまたは不完全なレートに基づいて見積もりを行うため、リクエストは受け入れられます。
- 予算予約: テナント残高は 1 つのカタログを使用して予約されますが、別のカタログを使用して決済されます。
- 使用状況台帳: キャッシュされたトークン、推論トークン、ツール呼び出し、またはバッチ単位は一般的な合計として保存され、正しく価格を変更することはできません。
- チャージバック エクスポート: 財務部門は、差異を説明するために必要なプロバイダ請求書のディメンションなしでテナントの合計を受け取ります。
- パートナー API: ダウンストリーム プロダクトは、価格が現在の価格、推定価格、廃止予定の価格、またはブロックされている価格であるかどうかを知らずに価格を公開します。
価格設計で保持すべき事実
事実: パブリック プロバイダーのドキュメントでは、通常、モデルとトークン カテゴリごとに価格が分かれています。入力トークン、キャッシュされた入力トークン、および出力トークンのレートは異なる場合があります。一部の使用状況レポートでは、キャッシュされた入力または推論トークンの数が公開されます。これは、ゲートウェイが合計トークンのみを保存するのではなく、使用状況のサブカテゴリを保存する必要があることを意味します。
事実: 価格設定は必ずしも純粋な従量課金制トークンではありません。一部のプロバイダーは、特定のモデル容量に関連付けられたコミットされた容量、プロビジョニングされたスループット、またはトークン ユニットを販売しています。これらのモードでは、単純なリクエストごとのトークン請求ではなく、時間、容量単位、またはモデル固有の入出力比に基づいてコストを計算できます。
事実: ホストされているツールと取得機能により、通常のモデル推論以外に追加の課金対象イベントが作成される場合があります。検索グラウンディング、ファイル検索、URL コンテキスト、コード実行、キャッシュ書き込み、エージェントの中間ステップには、別個の SKU マッピングが必要になる場合があります。
推奨事項: これらの事実を例外ではなくスキーマ要件として扱います。カタログでマッピングできない請求可能なディメンションが使用状況イベントに含まれている場合、ゲートウェイはトランザクションの価格を黙ってゼロに設定するのではなく、トランザクションを請求保留にする必要があります。
バージョン管理された価格カタログを作成する
価格カタログは、プロバイダー アダプターに埋め込まれた定数ではなく、ファーストクラスのテーブルまたはサービスである必要があります。カタログは 1 つの質問に答えるために存在します。この使用イベントでは、現時点で、このテナントとプロバイダー アカウントのコンテキストで、どの承認済みレートを使用する必要がありますか?
コアカタログフィールド
実際のカタログ行には、少なくとも次のフィールドを含める必要があります。
catalog_version_id: 見積、予約、決済、調整に使用される不変のバージョン。プロバイダ: アップストリームプロバイダまたは内部プロバイダアダプタ。provider_account_scope: グローバル、組織、プロジェクト、ワークスペース、BYOK テナント、リセラー アカウント、またはエンタープライズ契約。model_id_or_alias: プロバイダーに表示されるモデル ID または価格設定される内部モデル エイリアス。pricing_sku: ゲートウェイが決済に使用する正規の SKU。provider_meter_id: 利用可能な場合はオプションのアップストリーム請求書メーター。billing_unit: 入力トークン、キャッシュされた入力トークン、出力トークン、推論トークン、キャッシュ書き込み、検索クエリ、画像トークン、音声秒、バッチ単位、PTU 時間、または別の明示的な単位。region_scope: グローバル、リージョン、居住ゾーン、マーケットプレイス、またはデータ居住クラス。deployment_type: サーバーレス、バッチ、プロビジョニングされた、専用、微調整された、または内部サンドボックス。service_tier: 標準、優先、バッチ、高速、プロビジョニングされた、またはその他のゲートウェイ層。currency: マークアップ、税金、クレジット、または換算前のレートの通貨。rate: 正確な 10 進数のレート。バイナリ浮動小数点ではありません。minimum_unit: 請求可能な最小単位。rounding_rule: リクエストごと、請求書明細ごと、テナント期間ごと、またはプロバイダー定義。source_url: ドキュメント、プライスカード、契約リファレンス、または内部承認チケット。observed_at: 価格が検出またはインポートされたとき。Effective_fromおよびEffective_to: 有効期間。approval_state: ドラフト、レビュー済み、承認済み、非推奨、ブロック、または置き換え済み。
実装の重要な詳細は、カタログ バージョンがトラフィックによって使用されると不変であるということです。修正では、既存の元帳行が参照する履歴バージョンを変更するのではなく、新しいバージョンまたは調整エントリを作成する必要があります。
モデル エイリアスを価格設定 SKU から分離する
chat-default、support-fast、reasoning-premium などの内部エイリアスは、運用上の利便性を目的としています。プロバイダーに表示されるモデル ID や台帳内の価格設定 SKU を置き換えてはなりません。
使用状況イベントには、次の 3 つの ID をすべて保存する必要があります。
requested_model_alias: アプリケーションが要求したもの。upstream_model_id: ゲートウェイが実際に呼び出したもの。pricing_sku: 決済エンジンが決済に使用したもの。
これにより、エイリアスのプロモーションによる履歴の書き換えが防止されます。 chat-default が 8 月に 1 つのモデルを指し、9 月に新しいモデルを指す場合、8 月の使用量は 8 月のアップストリーム モデルと 8 月のカタログ バージョンに関連付けられたままにする必要があります。
不変のカタログ バージョンに対する引用
引用は、後で説明できる場合にのみ役に立ちます。ゲートウェイは、発送前にカタログ バージョンを選択し、それをプリフライト見積もりに使用し、予算予約に永続化して、最終決済まで実行する必要があります。
最小限のリクエストのライフサイクルは次のようになります。
<オル>推奨事項: 保守的な前提で見積もって予約し、回答後の使用状況から決定します。ストリーミング、再試行、ホストされたツール、長時間実行されるエージェント、キャッシュ ヒット動作については、正確なディスパッチ前の価格設定は困難です。目標は完璧な予測ではありません。目標は、エクスポージャを制御し、説明可能な和解を行うことです。
不明な請求可能なディメンションのフェール クローズ
最も危険な価格設定のバグは、無料使用になる SKU が欠落していることです。プロバイダーの応答に、マッピングが承認されていない使用状況バケットが含まれている場合、ゲートウェイは失敗して閉じられる必要があります。
請求保留をトリガーする例:
- モデル レスポンスには
cached_input_tokensが含まれていますが、カタログには一般的な入力および出力トークン レートのみが含まれています。 - 推論モデルは
reasoning_tokensを返しますが、推論 SKU が設定されていません。 - ホスト型検索ツールはクエリごとに課金されますが、ゲートウェイはモデル トークンのみを記録します。
- バッチ ジョブには割引が適用されますが、カタログでは標準のサーバーレス SKU にマッピングされます。
- プロビジョニングされた導入では時間単位の容量料金が発生しますが、テナント台帳ではトークンごとの決済が想定されます。
- リージョン展開では、アクティブなカタログに存在しない常駐修飾子が使用されます。
請求保留によってイベントが失われることはありません。生のプロバイダーの使用状況、正規化された使用法、リクエスト識別子、テナント識別子、プロバイダー アカウントの範囲、試行されたカタログ バージョン、欠落している SKU フィールド、および決済がブロックされた理由を保存する必要があります。カタログが更新され承認されると、保留キューを確定的に再生できるようになります。
承認前にプライスカードの差分チェックを使用する
プロバイダーの料金ページと API は常にマシンに対して安定しているとは限らず、契約によって公開料金が上書きされる場合があります。それでも、自動差分チェックはアラートとして役立ちます。顧客に表示される見積もりが影響を受ける前に、変更を検出する必要があります。
価格設定インポート パイプラインでは、新しく観察された価格カードと、最後に承認されたカタログおよびフラグを比較する必要があります。
- 新しいモデルまたは廃止されたモデル;
- 変更された入力、キャッシュされた入力、出力、または推論レート。
- 新しいトークン カテゴリまたはツール メーター;
- キャッシュ書き込み乗数またはキャッシュヒット乗数を変更しました。
- 新しい地域、居住地、または市場の修飾子。
- 一括割引ルールを変更しました。
- プロビジョニングされた容量ルールまたはコミットされた容量ルールの変更
- 通貨の変更;
- 四捨五入または最小単位の変更
- 公開価格カードとアカウント固有の契約料金との間の矛盾
推奨: スクレイピングとインポートをドラフト データとして扱います。請求されるトラフィック、パートナーに表示される価格設定、または輸出金融に影響を与える変更には人間の承認が必要です。内部実験ではサンドボックス カタログを使用できますが、明示的な支出上限を設定する必要があり、承認された顧客の請求と間違われることがないようにしてください。
価格設定 CI として見積もりテストを追加する
コード変更と同じ理由で、価格変更にはテストが必要です。小さな編集が多くのリクエスト形状に影響を与える可能性があります。見積もりテストは、カタログ行、SKU マッピング、プロバイダー アダプター、またはマークアップ ポリシーが変更されるたびに実行する必要があります。
価格設定面をカバーする合成リクエスト形状を使用します。
- 入力トークンと出力トークンを含む標準テキスト リクエスト;
- キャッシュされた入力トークンを使用したリクエスト;
- 別の推論を使用する、推論の多いリクエスト。
- 検索、ファイル、またはコード実行料金を伴うツール使用リクエスト
- 画像、音声、ビデオ、または生成されたメディア ユニットを含むマルチモーダル リクエスト
- 割引料金と遅延決済を伴うバッチジョブ;
- 時間単位の容量と波及動作を備えたプロビジョニングされた導入
- 地域または居住地を対象としたリクエスト;
- プロバイダー固有の契約料金を持つテナント;
- マークアップまたは割引ポリシーのあるパートナー テナント
各テストでは、最終的な合計以上の値をアサートする必要があります。選択したカタログ バージョン、SKU リスト、請求単位、料金、四捨五入動作、通貨、推定合計額、予約金額、および予想される決済行をアサートする必要があります。
引用テストの例
{
"名前": "cached_input_plus_reasoning_output_standard_tier",
「リクエスト」: {
"テナントID": "テナントテスト",
"model_alias": "reasoning-default",
"サービス層": "標準",
"地域": "グローバル",
"推定使用量": {
"input_tokens": 12000、
「cached_input_tokens」: 8000、
「出力トークン」: 1500、
「reasoning_tokens」: 3000
}
}、
"期待": {
"catalog_version_id": "2026-09-01-承認済み",
"required_skus": [
"テキスト入力",
"text_cached_input",
"テキスト出力",
「推論_出力」
]、
"approval_state": "承認済み",
"unknown_dimensions": []
}
}この種のテストは、キャッシュされたトークン SKU の欠落、古い推論レート、または 1 つのプロバイダー アカウント スコープにのみ表示される階層の不一致など、ダッシュボードに隠されているカタログの間違いを検出します。
プロバイダ請求書の寸法による調整
チャージバックの合計は調整に十分ではありません。ゲートウェイは、プロバイダーの請求書が使用するのと同じディメンションで台帳の行を集計し、それらの合計をテナント、チーム、キー、ユーザー、製品、ワークフローにマッピングし直す必要があります。
調整ジョブは、プロバイダー、アカウント、請求期間、メーター、モデル、SKU、地域、展開タイプ、サービス層、通貨、カタログ バージョンなどのフィールドごとにグループ化する必要があります。違いは既知の原因に分類する必要があります。
- 為替レートのタイミングまたは通貨換算
- リクエスト レベルと請求書明細レベルでの四捨五入。
- プロバイダの使用状況レポートの遅延
- ホストツールイベントが欠落しています;
- カタログ バージョンの不一致;
- プロバイダ側のクレジット、コミットメント、または企業割引
- 税金、マーケットプレイス手数料、非使用料
- 手動による調整または払い戻し。
推奨事項: プロバイダーのコスト率を顧客のチャージバック率とは別にモデル化します。プロバイダーの請求書には、顧客向けの価格を自動的に変更しないクレジット、コミットメント、割引、税金が含まれる場合があります。クリーンなシステムでは、プロバイダーが請求した金額と、承認されたゲートウェイ ポリシーに基づいてテナントに請求された金額の両方を説明できます。
財務およびパートナーに価格の出所を公開する
価格カタログは、内部の請求に依存するだけではありません。財務チーム、プラットフォーム管理者、パートナーは、価格が最新で信頼できるかどうかを知る必要があります。
管理者ビューとパートナー API を通じて来歴フィールドを公開します:
- 現在の見積レートと通貨;
- 発効日と終了予定日;
- ソース URL または契約参照;
- 承認状態;
- プロバイダー アカウントのスコープ;
- 値上げまたは割引ポリシー;
- 価格が見積もられるか、承認されるか、廃止されるか、ブロックされるか、または置き換えられるかどうか
- 最後の調整ステータス。
これにより、下流の製品が、上流の価格変更後に古い「最安モデル」の主張や固定の顧客価格を提示することを回避できます。また、予算と請求書が一致しない場合でも、財務部門に防御可能な証拠を提供します。
実装チェックリスト
- 発効日と承認状態を含む不変の価格カタログを作成する
- 一般的なトークンの合計のみを保存するのではなく、請求可能な単位を明示的に表します。
- 使用イベントごとに、リクエストされたエイリアス、アップストリーム モデル ID、価格設定 SKU を保存します。
- 見積もり、予約、元帳行、照合レコードに
catalog_version_idを保持します。 - 使用量にマップされていない請求可能なディメンションが含まれている場合はフェイルクローズされます。
- ドラフトのインポートと差分チェックを使用して、プロバイダの価格変動を検出します。
- カタログの変更が請求対象の顧客トラフィックに影響を与える前に承認を必要とする
- キャッシュされたトークン、推論トークン、ツール、バッチジョブ、プロビジョニングされたデプロイメント、地域修飾子の見積もりテストを追加します。
- プロバイダのコスト率と顧客のチャージバック率を分離する
- テナントに差異を割り当てる前に、プロバイダの請求書の寸法を調整します。
トレードオフ
バージョン管理が増えると、運用作業も増えます。 すべての価格変更には、インポート、レビュー、承認、テスト、展開が必要です。利点は、古い使用量が新しいレートで誤って再計算されることがないことです。
フェイルクローズすると、新しいモデルへのアクセスが遅れる可能性があります。 これは、請求される顧客トラフィックの正しいデフォルトです。内部実験の場合は、明示的な支出制限と明確なラベルを備えたサンドボックス カタログを使用します。
自動価格スクレイピングは便利ですが、信頼できるものではありません。 公開ページでは、レイアウトが変更されたり、契約割引が省略されたり、散文で価格が説明されたりする場合があります。自動化を使用してドリフトを検出し、請求に影響する前にレビューされたカタログ行を承認します。
完璧なプリフライト推定は非現実的です。 ストリーミング、再試行、エージェント ループ、キャッシュ ヒット、ホストされたツールによって、最終的な使用状況が変化する可能性があります。ゲートウェイは、保守的な予約と応答後の決済および明確な差異レポートを組み合わせる必要があります。
予測: 価格カタログがゲートウェイ インフラストラクチャになる
予測: AI の使用がチーム全体に広がるにつれて、価格カタログがモデル カタログと同じくらい重要になるでしょう。モデル ルーティングは、「このリクエストはどこに送られるべきか?」という質問に答えます。価格管理は、「このリクエストを見積もったり、予約したり、決済したり、説明したりできますか?」と答えます。
予測: プロバイダーがより多くのトークン カテゴリ、ツール メーター、キャッシュ ルール、容量プランを追加するにつれて、静的構成ファイルで価格を設定し続けるチームは苦戦するでしょう。プレッシャーは、アプリケーション開発者からではなく、まず金融機関やパートナーから来るでしょう。
結論
マルチモデル ゲートウェイでは、価格設定をサイドテーブルとして扱うことはできません。発効日、SKU マッピング、見積テスト、承認ワークフロー、請求書照合を備えたバージョン管理されたカタログが必要です。実際的なルールは単純です。請求されるすべての使用量バケットは承認されたレートにマッピングする必要があり、すべての見積もりは不変のカタログ バージョンを参照する必要があり、プロバイダーの価格が変更された後も、すべての決済された台帳行は説明可能な状態を維持する必要があります。
実稼働トラフィックにすでに影響を与えているディメンション（モデル、トークン カテゴリ、サービス レベル、リージョン、デプロイメント タイプ、キャッシュ動作、ホストされたツール）から始めます。次に、承認状態、フェールクローズ動作、および調整グループを追加します。この基盤により、価格ドリフトが請求インシデントになるのを防ぎます。