AI API アクセスの再販または埋め込みは、リクエストをモデル プロバイダーに転送するだけの問題ではありません。実際の運用作業は、下流のすべての顧客が独自の認証情報、制限、使用記録、請求イベント、サポート制御、および監査証跡を必要とするときに始まります。そのコントロール プレーンを管理するために、パートナーまたはリセラー API が存在します。
代理店、コンサルタント、SaaS ビルダー、リセラー パネル、および内部プラットフォーム チームにとって、パートナー API は推論 API の上に位置します。推論 API は、チャットの完了、埋め込み、画像生成、文字起こし、またはその他のモデル呼び出しを実行します。パートナー API は、これらの呼び出しに関するビジネス オブジェクト (顧客、API キー、キー グループ、支出制御、リクエスト履歴、残高トランザクション、非同期ジョブ、コールバック、アカウント状態など) を管理します。
共有プロバイダー キーは使い始めるのは簡単ですが、使い続けるのは難しいため、これは重要です。複数の顧客が同じ認証情報を使用すると、帰属が脆弱になります。虐待への対応は誰にでも影響を及ぼします。レート制限と残高はプールされます。請求に関する紛争は調査が困難です。回復力のあるリセラーのセットアップには、顧客範囲のアクセスと、何が起こったのか、誰が原因なのか、コストはいくらなのか、どの制御が適用されたのかを説明できる台帳が必要です。
パートナー API が行うべきこと
パートナー API は、信頼できるシステムのためのサーバー間の管理インターフェイスです。ブラウザ、モバイル アプリ、プラグイン、または信頼できない顧客コードに直接公開しないでください。バックエンド、プロビジョニング パネル、請求担当者、Telegram ボット、サポート コンソール、またはリセラー ポータルはパートナー API を呼び出して、ダウンストリーム アクセスを作成および管理します。
AI ゲートウェイのコンテキストでは、パートナー API は少なくとも 4 つの永続的な責任をサポートする必要があります。まず、顧客スコープの資格情報をプロビジョニングする必要があります。次に、これらの資格情報をグループ、プラン、プロジェクト、またはテナント境界に編成する必要があります。第三に、請求システムやサポート システムに情報を提供できる使用状況と取引記録を公開する必要があります。 4 番目に、キーの凍結、凍結解除、回転、移動、削除などのライフサイクル操作を提供する必要があります。
モデル ゲートはこのパターンの例です。そのパートナー API は、ボット、リセラー パネル、内部プロビジョニング システム、および信頼できる統合のためのサーバー間インターフェイスとして文書化されています。パートナー API キーによるベアラー認証を使用し、API キー、グループ、キーとグループの使用法、最近のリクエスト レコード、残高トランザクション、および非同期結果ポーリングの操作を公開します。これらはコントロール プレーンの機能であり、モデル推論エンドポイントではありません。
区別することが重要です。顧客には、AI API リセラー ポータル、ホワイト ラベル AI API パッケージ、代理店管理の AI 統合などのシンプルな製品画面が表示される場合があります。その表面の裏側では、パートナー システムには、すべての顧客に直接プロバイダー アカウントの作成を依頼せずに、認証情報の作成、プラン ルールの強制、メーター消費、サポート イベントの処理を行うための十分な構造が必要です。
代理店や SaaS チームが必要とする場合
パートナー API は、AI アクセスが 1 回限りの統合ではなく、製品またはマネージド サービスの一部である場合に必要になります。代理店は、各クライアントが個別の予算、個別の使用状況レポート、個別のキル スイッチを持つように、代理店向けの AI API を必要とする場合があります。 SaaS 企業は、エンド ユーザーがキーをまったく見ない場合でも、テナントごとのキーが必要になる場合があるため、プラットフォームはモデルのコストを適切なアカウントに帰属させることができます。社内プラットフォーム チームには、部門、環境、またはアプリケーションに対してプロジェクト レベルの境界が必要な場合があります。
顧客 API キーのプロビジョニング、プランベースの支出制限、委任された使用量分析、または自動停止とローテーションが必要な場合は、リセラーまたはパートナー API を検討する必要があります。顧客が基礎となるモデルプロバイダーから直接ではなく、貴社からアクセスを購入する場合にも、それを考慮する必要があります。その場合、顧客関係、請求書、サポート パス、および許容範囲の適用は、部分的または完全に製品に属します。
一部の顧客にとっては、直接プロバイダー アカウントが適切な選択となる場合もあります。これらにより、購入者はベンダーを直接管理し、ベンダーの請求書を明確にすることができます。しかし、これらにより、再販業者の統一請求、顧客レベルのハードキャップ、サポートの優先順位付け、モデルの移植性が難しくなります。プロバイダー管理 API は、プロジェクト、ワークスペース、API キー、予算、またはレポートを公開する場合がありますが、これらのオブジェクトはベンダー間で常に同等であるとは限りません。マルチモデル ゲートウェイ上のパートナー API により、顧客向けの契約に正規化されたレイヤーが提供されます。
コア データ モデル
永続的なパートナー統合は、明確なローカル データ モデルから始まります。少なくとも、顧客アカウント、外部顧客 ID、プラン、請求モード、API キー、キー グループ、使用制限、モデル権限、現在の状態、およびサポート メタデータを定義します。アカウント所有者、請求所有者、資格情報プリンシパル、顧客テナント、およびエンドユーザーが同じ ID であると想定しないでください。リセラー環境と SaaS 環境では、これらは異なることがよくあります。
実際のモデルには、次のオブジェクトが含まれることがよくあります。
- 顧客またはテナント: 帰属と請求に使用される商用またはアプリケーションの境界。
- API キー: 顧客、アプリ、環境、または内部サービスが推論 API を呼び出すために使用する認証情報。
- グループまたはプラン境界: 共有制限、モデル権限、価格設定ルール、またはレポート用のコンテナ。
- 使用状況レコード: リクエスト ID、顧客、キー、グループ、モデル、エンドポイント、トークン数、ステータス、タイムスタンプ、コスト コンポーネントを記述する正規化されたイベント。
- 残高トランザクション: クレジット、借方、調整、返金などの財務元帳エントリ。
- 非同期ジョブ:後で完了する可能性があり、ポーリング、コールバック処理、および最終的な請求状態が必要な、送信されたモデル タスク。
- 監査イベント:プロビジョニング、制限変更、キー ローテーション、一時停止、サポート アクション、および調整結果の内部記録。
ゲートウェイが同様のオブジェクトを公開する場合でも、このモデルはシステム内に存在する必要があります。ローカル データベースは、ビジネスの目的をゲートウェイの状態 (どの顧客がどのプランを購入したか、キーが作成された理由、どの請求明細行がどの使用状況イベントを使用したか、タイムアウトまたはコールバック障害が発生したときに何が起こったか) に結び付ける場所です。
プロビジョニング ワークフロー
プロビジョニングは、単一のベスト エフォート スクリプトではなく、ステート マシンとして扱う必要があります。一般的なワークフローは、システム内の顧客の作成またはマッピング、プランの選択、スコープ付きゲートウェイ キーの作成、グループへのキーの割り当て、制限とモデル権限の適用、返されたシークレットのみを安全に保存し、承認されたチャネルを通じてアクセスを提供することから始まります。
有用な状態には、pending、key_created、limits_applied、delivered、active、 一時停止、rotation_required、削除。これらの状態により、再試行とサポート アクションがわかりやすくなります。キーの作成は成功したが、制限割り当てがタイムアウトになった場合、システムはどこから再開すればよいかを認識している必要があります。顧客が前払いクレジットから後払い請求書発行にアップグレードする場合、システムはどのコントロールがいつ変更されたかを記録する必要があります。
認証情報の処理には特別な注意が必要です。 API キー シークレットの配信は、1 回限りの安全なイベントである必要があります。秘密を記録しないでください。プロバイダーの資格情報を顧客のブラウザーやモバイル アプリに送信しないでください。顧客のサポートに必要なもののみを保存し、本番ワークロードが計画されたカットオーバー中に古いキーと新しいキーの両方を実行できるローテーション パスを提供します。
より広範な認証情報設計の場合、顧客スコープのゲートウェイ キーは、ローテーション、凍結、最小権限、環境の分離、サポートをカバーするより大きな API キー管理戦略の一部である必要があります。
冪等性は課金機能です
冪等性は単なる API の利点ではありません。パートナー API の自動化では、顧客と財務システムを重複した副作用から保護します。キーを 2 回作成したり、クレジットを 2 回追加したり、タイムアウト後に矛盾する制限を適用したりすると、顧客に実際の影響が生じる可能性があります。
パートナーの操作を変更するには、安定した冪等性キーが必要です。 Model Gate は、POST、PATCH、および DELETE パートナー API リクエストの変更に対するこの期待を文書化し、タイムアウト後に同じ冪等キーを使用して同じ論理操作を再試行するように実装者に指示します。また、冪等性レコードの 7 日間の保存期間も文書化されています。
キーは、ランダムな再試行からではなく、ビジネス上の意図から派生する必要があります。たとえば、create-key:customer_123:prod:plan_pro は安定した論理操作です。同じ操作を新たに再試行する場合は、それを再利用する必要があります。別の環境用に 2 番目のキーを作成する後の操作では、別の冪等キーを使用する必要があります。
ローカル操作台帳には、リクエスト メソッド、エンドポイント、冪等キー、外部顧客 ID、ペイロード ハッシュ、ゲートウェイ リクエスト ID、応答ステータス、および最終結果を保存する必要があります。このレコードは、ワークフロー エンジンとゲートウェイの間のブリッジです。また、サポート チームや財務チームは、ワーカーがクラッシュしたとき、ネットワーク タイムアウトが発生したとき、またはクレジット調整が 2 回適用されたと顧客が主張したときに何が起こったのかを回答する方法を提供します。
使用量、測定、請求
AI の使用量ベースの請求は、ダッシュボードのスクリーンショットや広範囲にわたるプロバイダーの請求書ではなく、正規化された記録に基づく必要があります。便利な使用状況台帳には、リクエスト ID、顧客 ID、キー ID、グループ ID、モデル、エンドポイント、モード、ステータス、トークンと価格の内訳、タイムスタンプ、決済状態が含まれます。関連する場合、入力、出力、キャッシュされた入力、ツールの使用状況、バッチ モード、プロバイダー固有の調整などのトークン カテゴリを保持する必要があります。
金額、クレジット、残高、乗数、および使用量は、正確な小数として解析される必要があります。 Model Gate は、パートナー API の財務フィールドと使用状況フィールドを JSON 10 進数文字列として文書化し、実装者に 2 進浮動小数点ではなく任意精度の 10 進数演算を使用するように指示します。この設計により、請求書、残高表示、販売代理店マージンの計算で目に見える小さな丸め誤差が回避されます。
ストライプ スタイルの従量課金にも同様の要件があります。明示的な顧客 ID、使用量の値、タイムスタンプ、ディメンション、冪等性 ID です。ゲートウェイの使用状況を外部の課金プロバイダーにエクスポートする場合は、詳細をあまり早く折りたたまないでください。簡素化された単位で請求することもできますが、リクエストの記録、取引残高、請求書、返金、カスタマー サポート チケットを調整するには十分な出所が必要です。
プランとマージンを設計しているチームの場合、パートナー メーターは AI API の請求に直接接続されます。ゲートウェイはモデルのアクセスと使用状況の分析を正規化できますが、リセラーには価格カタログ、発効日、端数処理ポリシー、税金と請求書のルール、およびローカル使用状況、ゲートウェイの状態、残高トランザクション、コールバック イベント、請求プロバイダーのレコードを比較する調整ジョブが必要です。
支出制限、割り当て、レート制限
リセラー製品には多くの場合、ハード制御が必要です。プロバイダーのダッシュボードは予算やアラートを提供する場合がありますが、アラートは強制的な強制と同じではありません。一部のプロバイダー プロジェクトの支出制限はソフトしきい値です。これらは動作を通知またはガイドしますが、製品が約束した顧客境界で使用を停止できない場合があります。
パートナー API を使用すると、顧客、キー、グループ、プラン、またはモデル クラスごとに制限を強制できるようにする必要があります。プリペイド クレジットは残高が明示されているため、制限が容易です。後払い請求は企業の調達に適合しますが、より強力な異常検出、与信管理、回収ワークフローが必要です。ハードリミットは再販業者のマージンを保護しますが、顧客のワークロードが中断される可能性があります。ソフト アラートは混乱を軽減しますが、過剰な支出を許す可能性があります。
レート制限にも明確な所有権が必要です。顧客は、リセラーレベルの制限、ゲートウェイレベルの制限、またはアップストリームプロバイダーの制限に達する可能性があります。顧客向けのドキュメントでは、HTTP 429 応答の処理方法、特に Retry-After の動作について説明する必要があります。 Model Gate は、HTTP 429、Retry-After、および X-RateLimit ヘッダーを使用してレート制限応答を文書化します。お客様は、すぐに再試行して負荷の急増や過剰な支出を引き起こすのではなく、これらのヘッダーに従ってバックオフする必要があります。
リクエスト履歴、ページネーション、保持
最近のリクエスト レコードは、サポート、デバッグ、および短期的な調整に役立ちます。ゲートウェイがその保持モデルを明示的に約束しない限り、これらは永続的な財務データベースの代替にはなりません。リクエスト履歴 API を操作ウィンドウとして扱います。請求、監査、サポート、分析に必要なレコードをエクスポートして保存します。
パートナー API は通常、収集エンドポイントにカーソル ページネーションを使用します。 Model Gate ドキュメントの制限に加えて、不透明なカーソルのページネーションと UTC RFC3339 タイムスタンプ。カーソルは不透明なトークンとして扱う必要があります。これらを手動で構築したり、ビジネス上の意味をその中に保存したり、カーソルの形状を想定した請求ロジックを構築したりしないでください。エクスポーターは、最後に成功したチェックポイントを記憶し、重複レコードを安全に処理し、ページ位置だけではなくリクエスト ID によって調整する必要があります。
保持期間もサポートに影響します。顧客が 2 か月前の請求書について尋ねた場合、その答えは、最近のリクエストのエンドポイントに生のイベントがまだあるかどうかに依存すべきではありません。必要な永続的なメタデータを保存します: 顧客、キー、グループ、モデル、リクエスト ID、ステータス、使用量、決済コスト、タイムスタンプ、請求書のマッピング。
コールバック、ポーリング、および非同期推論
非同期推論は、ファーストクラスのワークフローとしてモデル化する必要があります。長時間実行される画像、音声、バッチ、またはツールを多用するジョブは、最終的な使用量とコストが判明する前にジョブ ID を返す場合があります。パートナー システムは、送信されたジョブを保存し、コールバックをポーリングまたは受信し、処理、完了、失敗、期限切れ、およびキャンセルの状態を処理し、最終的な決済ポリシーに従って請求する必要があります。
ポーリングは実装が簡単で、テストも簡単です。コールバックは待ち時間を短縮し、不必要なポーリング負荷を回避しますが、署名検証、リプレイ保護、重複排除、再試行処理、配信不能処理が必要です。コールバックが失敗した場合でも、永続的な請求ギャップが生じてはなりません。リコンシリエーション ワーカーは、非同期ジョブの状態、コールバック イベント、リクエスト履歴、および残高トランザクションを比較する必要があります。
Model Gate では、パートナー API での非同期結果ポーリングと API ドキュメントでのコールバック動作について説明しています。再販業者の製品では、これらの機能を復元力のある配信モデルに組み込む必要があります。顧客には明確なジョブの状態と最終結果が表示される必要がありますが、パートナーのバックエンドはサポートと請求に必要な運用の詳細を保持します。
出所を失わないプロバイダの抽象化
マルチモデル ゲートウェイは、プロバイダの不必要な違いを顧客から隠すことができます。これは、プロバイダー間で 1 つの OpenAI 互換インターフェイス、1 つの請求関係、および 1 つの運用モデルが必要な場合に役立ちます。しかし、抽象化によって出所が消去されるべきではありません。どのプロバイダー、モデル、エンドポイント、リクエスト モード、トークン カテゴリがコストや障害を引き起こしたかを知る必要があります。
これは、プロバイダーが価格を変更したり、モデルを廃止したり、レート制限を変更したり、異なる管理セマンティクスを公開したりする場合に特に重要です。 OpenAI プロジェクト、Anthropic ワークスペース、クラウド API ゲートウェイ キー、サードパーティ AI ゲートウェイ仮想キーはすべて、関連する問題を解決しますが、同一のコントロールを公開するわけではありません。リセラーのコントロール プレーンには独自の正規化されたモデルが必要で、デバッグ、インシデント対応、顧客の信頼、移行計画をサポートする出所としてプロバイダー固有のフィールドを扱う必要があります。
計画の設計は、AI モデルの選択とも関係します。顧客は単純な層を購入することもできますが、バックエンドは品質、遅延、価格、リージョン、または可用性に基づいてモデル間でリクエストをルーティングする場合があります。コストが変化したり、成果が異なる場合に、それらの選択肢を説明できる十分な詳細を保持してください。
サポートと不正行為の制御
サポート ワークフローは、最初の顧客インシデントが発生する前に設計する必要があります。オペレーターは、最近のリクエストのメタデータを検査し、急増の原因となった顧客とキーの特定、アクセスの凍結または凍結解除、認証情報のローテーション、グループ間でのキーの移動、契約上適切な制限の調整、すべてのアクションの監査イベントの保存を行う必要があります。
優れたサポート コンソールでは、デフォルトで生のプロンプトを公開する必要はありません。メタデータファーストの可観測性は、通常、プライバシーと保持のリスクを軽減しながら、請求と運用の優先順位付けに十分なコンテキストを提供します。未加工のコンテンツを保存または検査する場合は、アクセス制御、保存期間、顧客への通知、監査ログを定義します。
不正行為の制御は正確である必要があります。 1 つのキーを凍結しても、無関係なテナントが一時停止されるべきではありません。騒がしい顧客は、他のすべての顧客の共有アカウント残高やプロバイダーのキャパシティを使い果たさないようにする必要があります。グループ レベルおよびキー レベルの制御により、応答が迅速になり、中断が軽減されます。
ホワイト ラベル、共同ブランド、または透過的なアクセス
再販業者は、基盤となるゲートウェイとモデル プロバイダーについて顧客がどの程度知っているかを判断する必要があります。ホワイトラベル AI API では、再販業者のブランドのみが表示される場合があります。共同ブランドのサービスでは、ゲートウェイまたはプロバイダーが開示される場合があります。透過的なエンタープライズ製品では、モデルの来歴、プロバイダーの地域、および詳細な使用カテゴリーが表示される場合があります。
単一の正解はありません。詳細を非表示にすると、顧客の製品がよりシンプルになります。詳細を開示することで、信頼、調達、コンプライアンスのレビュー、インシデント処理を向上させることができます。重要なのは一貫性です。請求書、サポート プロセス、利用規約、レート制限の言語、およびデータ処理のコミットメントは、アクセスの提示方法と一致している必要があります。
よくある間違い
最も一般的な失敗は、多くの顧客に対して 1 つの共有 API キーを使用していることです。これは、請求に関する紛争、不正行為の報告、遅延の急増、クォータの問題、または顧客離れイベントが発生するまで機能します。顧客スコープの認証情報がなければ、すべての調査は推測に頼ることになります。
もう 1 つのよくある間違いは、冪等性を持たずに変更操作を再試行することです。タイムアウトは曖昧です。ワーカーが応答を受信しなくても、操作は成功した可能性があります。安定した冪等キーとローカル操作台帳により、キーの重複、クレジット、状態の変更が防止されます。
丸め誤差も過小評価されがちです。 10 進数の金額フィールドと使用状況フィールドを浮動小数点数として解析すると、請求書全体で小さな差異が蓄積される可能性があります。クレジット、残高、乗数、決済コストには任意精度の小数演算を使用します。
チームはプロバイダーの予算も過信します。アラートとプロジェクト レベルの制限では、再販業者のプランで約束された顧客レベルのハード キャップが強制されない場合があります。可能な場合はゲートウェイまたはパートナー層で制限を適用し、完了後に精算された使用量を調整します。
最後に、合計だけから請求を作成しないでください。合計は有用な要約ですが、請求書には防御可能な系列が必要です。リクエスト ID、顧客 ID、ゲートウェイ リクエスト ID、使用状況の詳細、トランザクション レコード、請求イベント ID、決済状態を保存します。
実装チェックリスト
顧客のライフサイクルから始めます。顧客の作成、アップグレード、一時停止、再アクティブ化、ローテーション、および削除の方法を定義します。各状態をパートナー API オペレーションとローカル監査イベントにマッピングします。
次に、オペレーション台帳を設計します。すべての変化するパートナー API リクエストには、安定した冪等性キー、ペイロード ハッシュ、利用可能なゲートウェイ リクエスト ID、応答ステータス、再試行回数、および最終結果が必要です。この台帳は、信頼できるパートナー API 自動化のバックボーンです。
次に、使用状況のエクスポートと調整を構築します。スケジュールに従ってリクエストとトランザクションのレコードをエクスポートします。正確な小数を使用してください。欠落しているイベント、重複した請求書の送信、未解決の非同期ジョブ、コールバックの失敗、請求書の不一致がないか確認します。
その後、顧客のセルフサービス ビューを慎重に公開します。使用状況、残りの予算、現在のキー、ローテーション オプション、制限、最近の失敗を表示します。プロバイダーの資格情報や無関係なテナント データを公開しないでください。可能な場合、サポート アクションを監査可能にし、元に戻せるようにします。
最後に、顧客向けの再試行と制限動作を文書化します。 429 の処理、キー ローテーションの期待、非同期ジョブの状態、使用状況レポートの遅延、ハード キャップ、ソフト アラート、リセラー制限、ゲートウェイ制限、アップストリーム プロバイダー制限の違いについて説明します。
結論
パートナーおよびリセラー API は、AI モデルへのアクセスを信頼性の高い製品に変えるコントロール プレーンです。顧客を対象とした認証情報を作成し、それらをグループまたはプランに編成し、支出とレートの制御を強制し、使用状況とトランザクションの記録を公開し、非同期ワークフローをサポートし、ローテーション、凍結、調整などのサポート操作を提供する必要があります。
中心的な原則は単純です。顧客向けのすべての約束には、耐久性のあるバックエンド オブジェクトと監査証跡が必要です。個別の請求を約束する場合は、個別の帰属を作成してください。予算を約束した場合は、それを執行し、調整してください。操作を再試行する場合は、操作を冪等にしてください。使用量を請求する場合は、正確な 10 進数の記録とリクエスト レベルの出所を保存してください。
Model Gate のパートナー API 機能は、サーバー間認証、API キーとグループの自動化、10 進数の使用法と財務フィールド、リクエスト履歴、残高トランザクション、非同期結果ポーリング、冪等性要件、レート制限応答、コールバック、統合請求、API キー管理、使用状況など、OpenAI 互換のマルチモデル ゲートウェイのコントロール プレーンの回避策に対処しているため、重要です。分析とチーム管理。これらのプリミティブを慎重に使用すると、代理店、SaaS チーム、再販業者は、請求管理や運用責任を放棄することなく、AI API アクセスをパッケージ化できるようになります。