AI API リセラー ポータルの構築: テナント プロビジョニング、使用量測定、請求、テレグラム運用

クライアント用に AI アクセスをパッケージ化する場合は、上流のプロバイダー キーをクライアントに渡さないでください。顧客スコープのキーを発行し、すべてのリクエストの前にテナント制限を適用し、独自の台帳に使用状況を記録し、請求可能な合計を請求システムに同期するリセラー層を構築します。

このガイドでは、代理店、コンサルタント、SaaS ビルダー向けの AI API の実用的な運用モデルについて説明します。これはお客様の事例研究ではありません。これは、パートナー API、内部ゲートウェイ、または複数のモデル プロバイダーの前でカスタム プロキシを使用するかどうかに合わせて適応できるリファレンス アーキテクチャです。

再販業者ポータルのアーキテクチャ

安全な再販業者ポータルでは、次の 4 つの責任が分離されます。

• パートナー管理: 顧客、プラン、キー、制限、サポート ワークフローを作成するための社内アプリ。
• リクエストの強制: 顧客キーの認証、ポリシーのチェック、リクエストのルーティング、制限を超えるトラフィックのブロックを行うゲートウェイ パス
• 使用量アカウンティング: リクエストレベルの使用量と価格設定の入力を記録する耐久性のある台帳。
• 請求と運用: スケジュールされた請求書の同期、アラート、キーのローテーション通知、サポート エスカレーション

一般的なフローは次のようになります。

パートナー管理アプリ
  → パートナーAPI
    → 顧客/ワークスペースの記録
    → 顧客スコープの API キー
    → プラン、モデル、予算、レート制限
    → リクエストゲートウェイ
    → 利用台帳
    → 請求同期
    → 電報通知ボット

事実: OpenAI では、コラボレーションのためにユーザーベースの API キーを共有せず、代わりにプロジェクトベースのキー、割り当てられたメンバー、および分離されたレート制限と支出制御を持つ個別のキーを使用することを推奨しています。 OpenAI のサービス規約では、サードパーティとの間で API キーを購入、販売、譲渡することも禁止されています。これらの事実は、アップストリーム認証情報がサーバー側に残り、顧客が独自のダウンストリーム キーを受け取るという再販業者の設計を裏付けています。

推奨事項: 顧客、プロジェクト、または環境ごとに 1 つのダウンストリーム キーを発行します。 1 つの顧客キーを複数のエンド クライアントで再利用しないでください。ドキュメント、ブラウザ コード、モバイル アプリ、ログ、またはクライアント サポート メッセージでアップストリーム プロバイダの認証情報を公開しないでください。

テナント データ モデル

テナント モデルでは分離を明示する必要があります。少なくとも、次のフィールドを保存します。

partner_id
顧客ID
ワークスペースID
api_key_id
プランID
請求状況
支出制限
レート制限
allowed_models
telegram_chat_id
use_ledger_id
作成日
更新済み
取り消し済み_at

より大きなポータルでは、前払い残高、通貨、課税地域、請求書の顧客 ID、サポート層、不正使用ステータス、一時的なオーバーライドのフィールドを追加します。

顧客レコードの例

{
  "パートナーID": "パートナー_123",
  "customer_id": "cust_acme",
  "workspace_id": "ws_prod",
  "plan_id": "growth_api",
  "billing_status": "アクティブ",
  "支出制限": {
    "期間": "月",
    「hard_cap_usd」: 500、
    "alert_thresholds": [0.5、0.8、0.95]
  }、
  "レート制限": {
    「1 分あたりのリクエスト数」: 120、
    「1日あたりのトークン数」: 2000000
  }、
  "allowed_models": ["ファストチャット", "推論標準"],
  "telegram_chat_id": "-1001234567890",
  "usage_ledger_id": "ledger_cust_acme"
}

推奨事項: customer_id、workspace_id、api_key_id は別の概念として扱います。顧客は複数のワークスペースを持っている場合があり、各ワークスペースには個別の運用キー、ステージング キー、および開発キーが必要になる場合があります。これにより、失効、デバッグ、使用状況の特定がはるかに簡単になります。

新規顧客のオンボーディング シーケンス

信頼性の高いオンボーディング フローは、設計上退屈なものです。毎回同じレコードが生成され、監査証跡が残されるはずです。

<オル>

顧客を作成します: 法人名、請求先担当者、技術担当者、内部所有者を保存します。

ワークスペースを作成する: お客様がプログラムで統合する場合は、本番環境とテストを分離します。

プランの割り当て: 含まれるモデル、マークアップ、請求頻度、サポートの期待値を定義します。

制限の設定: 支出上限、リクエスト制限、トークン制限、バースト ポリシーを構成します。

API キーの作成: お客様の環境向けにスコープ指定されたキーを発行します。

統合手順を送信する: ベース URL、認証形式、モデル リスト、制限、サポート チャネルを提供します。

アラートを有効にする: Telegram または別の運用チャネルに接続して、残高不足、鍵、停止、請求の通知を受け取ります。

テスト リクエストを実行します。 認証、使用状況の記録、モデル アクセス、請求書のマッピングを検証します。

推奨事項: オンボーディングをべき等にします。管理アプリが「顧客の作成」操作を再試行する場合、重複した請求レコードや重複した API キーを作成しないでください。プロビジョニング呼び出しには、外部 ID と冪等キーを使用します。

リクエスト時の予算管理

最も重要な強制は、リクエストが上流モデルに到達する前に行われます。ゲートウェイは、プロバイダーがすでに料金を請求した後でのみ、顧客が予算を超過していることを認識すべきではありません。

このプリフライト シーケンスを使用します:

<オル>

ダウンストリーム API キーを認証します。

partner_id、customer_id、workspace_id を解決します。

キーがアクティブであり、取り消されていないことを確認します。

請求ステータスを確認します: アクティブ、試用中、前払い、一時停止、期限超過、または一時停止。

現在の請求期間のハード支出上限を確認します。

1 分あたりのリクエスト数や 1 日あたりのトークン数などのレート制限を確認します。

リクエストされたモデルがお客様のプランで許可されているかどうかを確認します。

モデル、最大トークン、リクエスト パラメータから考えられる最大コストを見積もります。

ポリシーが合格した場合にのみリクエストをルーティングします。

if key.revoked:
    拒否(401、「APIキーが取り消されました」)
customer.billing_status が [「一時停止」、「一時停止」、「期限超過」] の場合:
    拒否(402、「請求ステータスが使用を許可していません」)
requested_model が customer.allowed_models にない場合:
    拒否(403, "モデルはこのワークスペースに対して有効ではありません")
current_period_spend +estimated_max_cost > customer.hard_cap の場合:
    拒否(402, "使用制限を超えました")
rate_limit_exceeded(customer_id, requested_model) の場合:
    拒否(429, "レート制限を超えました")
Route_request()

事実: OWASP API セキュリティ トップ 10 2023 では、オブジェクト承認の破損、認証の破損、および無制限のリソース消費が主要な API リスクとして挙げられています。これらは再販業者ポータルに直接マッピングされます。つまり、あるテナントが別のテナントのデータを読み取ってはならず、キーがバイパス可能であってはならず、また、ある顧客が無制限のプロバイダー支出を生み出すことができてはなりません。

トレードオフ: 厳格なハードキャップにより証拠金は保護されますが、正当なスパイクが妨げられる可能性があります。良い妥協案は、有効期限、承認者、理由、監査ログ エントリを含む一時的な上書きワークフローです。

信頼できる情報源としての使用状況台帳

リアルタイムのアクセス制御のために、独自の使用状況台帳を保管してください。外部請求ツールは請求書発行には優れていますが、通常はミリ秒レベルの許可または拒否の決定を行うのには適していません。

使用状況イベントでは、プロバイダーの請求書を照合し、顧客の請求書を説明し、紛争をデバッグするのに十分な詳細を取得する必要があります。

{
  "request_id": "req_01J...",
  "idempotency_key": "idem_abc123",
  "パートナーID": "パートナー_123",
  "customer_id": "cust_acme",
  "workspace_id": "ws_prod",
  "api_key_id": "key_live_789",
  "モデル": "推論標準",
  "input_tokens": 1850、
  「出力トークン」: 420、
  "cached_tokens": 1200、
  「プロバイダーコスト」: 0.0142、
  「再販業者価格」: 0.0230、
  "通貨": "USD",
  "タイムスタンプ": "2026-08-02T10:15:30Z",
  "ステータス": "成功"
}

失敗したリクエストも記録しますが、請求対象となる失敗とそうでない失敗を区別します。プロバイダーのタイムアウト、検証の失敗、顧客のキャンセル、再試行、安全ブロックは、発生時期に応じて異なる会計結果をもたらす可能性があります。

推奨事項: リクエストが受け入れられたときに保留中のレジャー イベントを書き込み、トークンの使用量とコストがわかったらイベントを完了します。これにより、ルーティング前に予算を予約し、完了後に最終的な金額を修正できます。

調整パターン

<オル>

リクエストレベルのイベントを内部台帳に保存します。

顧客、モデル、請求期間ごとに使用量を集計します。

内部合計を上流プロバイダの請求書または使用量のエクスポートと比較します。

請求書を発行する前に重大な差異を調査する

請求可能な使用量の概要を請求システムに同期します。

トレードオフ: 要約された使用量を同期すると、請求イベントの量と複雑さが軽減されますが、顧客の請求書の詳細が少なくなる可能性があります。顧客がモデルレベルまたはプロジェクトレベルのレポートを必要とする場合は、それらのディメンションを請求同期または顧客ダッシュボードに保存します。

使用量ベースのメーターとの請求同期

使用量ベースの請求システムは通常、製品と価格の定義、使用量イベントの取り込み、請求期間にわたる集計、請求書の生成、エラーの監視というパターンに従います。たとえば、Stripe Billing は、イベント名、顧客識別子、数値、オプションのタイムスタンプ、オプションの冪等性識別子、およびオプションのディメンションを含むメーター イベントをサポートします。

AI API の請求の場合、一般的なメーターの選択肢は次のとおりです。

• トークンの合計: 価格設定が入力トークンと出力トークンに密接に関係している場合に役立ちます。
• リクエスト数: シンプルなプランやトークンの少ない API 呼び出しに役立ちます。
• モデル固有の単位: プレミアム モデルのマージンが異なる場合に便利です。
• シートまたはアクティブなワークスペース: ハイブリッド SaaS プラス使用量プランに役立ちます。

事実: ストライプ メーターは、sum、count、last などの集計式をサポートしています。これらは、トークンの合計、リクエスト数、シートやアクティブな制限などの状態に似た値にマッピングされます。

毎日の請求同期により、次のようなメーター イベントが作成される場合があります。

{
  "event_name": "ai_tokens_used",
  "顧客": "ストライプ顧客_456",
  「値」: 2270000、
  "タイムスタンプ": "2026-08-02T23:59:00Z",
  "idempotency_key": "cust_acme_2026-08-02_tokens",
  「寸法」: {
    "プラン": "growth_api",
    "モデルファミリー": "標準"
  }
}

推奨事項: 内部台帳は請求書よりも細かく管理してください。サポート、不正行為のレビュー、レート制限の調整、マージン分析のためのリクエストレベルの記録を保持しながら、毎日のトークン合計を請求できます。

Telegram を記録システムにしない Telegram の操作

テレグラムはオペレータの迅速なワークフローに役立ちます。サポート チームはすでにメッセージに気づき、ボットはアラートを送信でき、顧客はダッシュボードにログインせずにオンボーディング手順を受け取ることができます。ただし、請求、セキュリティ、サポートに関する決定の監査証跡は Telegram だけであってはなりません。

優れた Telegram ワークフローには次のようなものがあります。

• 上限の 50%、80%、95% での低残高または高額支出のアラート
• ドキュメントへのリンクとマスクされたキー名を含む新規顧客のオンボーディング メッセージ
• API キーのローテーションの前後の通知。
• プロバイダの停止または機能低下したモデルのアラート
• お客様が 401、402、403、または 429 エラーを繰り返し発生した場合の人間によるサポートのエスカレーション

事実: Telegram Bot API 呼び出しは HTTPS 経由でボット トークン エンドポイントに対して行われ、Telegram Webhook には Webhook 発信元の検証に役立つシークレット トークン ヘッダーを含めることができます。

推奨事項: Telegram チャット ID をテナント メタデータとして保存しますが、顧客全体に公開しないでください。ボットによってトリガーされたすべての管理アクションを、アクター、タイムスタンプ、顧客、古い値、新しい値、理由とともに内部監査ログに記録します。

セキュリティと隔離のチェックリスト

アクセスを販売する前に、顧客が積極的に境界を越えようとしているかのように、テナントの分離をテストします。

• 顧客 A は顧客 B の API キーを表示できません。
• 顧客 A は顧客 B の使用状況、請求書、制限、Telegram チャット ID、または請求ステータスを表示できません。
• 取り消されたキーは、すべてのリクエスト パスで即座に失敗します。
• 請求が一時停止された顧客は、キャッシュされたセッションや古いキーを使用して支払いを続けることはできません。
• お客様は、割り当てられたプラン以外のモデルをリクエストすることはできません。
• レート制限は、グローバル IP アドレスだけでなく、顧客とワークスペースごとに適用されます。
• Webhook ハンドラーは、サポートされている場合、署名またはシークレット ヘッダーを検証します。
• すべてのプロビジョニング、制限の変更、キーのローテーション、請求の上書きにより、監査ログ エントリが作成されます。
• 再試行ロジックでは冪等キーを使用するため、重複したリクエストによって顧客に二重請求が行われることはありません。
• サポート ツールは秘密を隠し、鍵を公開またはローテーションできる人を制限します。

予測: 再販業者ポータルは、多くのモデルへのアクセスだけでなく、ガバナンスと請求の明確さでもますます競争するようになります。お客様は、標準機能として、プロジェクトごとの使用法、明確な請求書、高速なキー ローテーション、および厳しい支出管理を期待します。

早めに決定すべき重要なトレードオフ

前払いと後払い

プリペイド残高により信用リスクが軽減され、強制締め切りが簡単になりますが、顧客は中断を嫌う場合があります。後払い請求は既存の顧客にとってよりスムーズですが、信用調査、督促ワークフロー、強力な異常検出が必要です。

単一の混合価格とモデル固有の価格

混合価格の方が説明しやすいです。モデル固有の価格設定によりマージンが保護され、効率的なモデル選択が促進されます。多数のモデルを提供する場合は、顧客向けのシンプルなモデル カタログを公開し、プロバイダー固有の不必要な複雑さを非表示にします。

リアルタイム測定と遅延請求

リアルタイム測定により、支出上限と前払い残高が有効になります。また、永続的な書き込み、リプレイ処理、および調整も必要です。請求の遅延は簡単ですが、制限が適用される前に無駄な支出にさらされる可能性があります。

テレグラム優先のサポートとダッシュボード優先のサポート

Telegram は高速で、多くのオペレーターにとって馴染みのあるものです。ダッシュボードは、監査可能性、エクスポート、権限、および顧客のセルフサービスの点で優れています。通知と承認には Telegram を使用しますが、正規レコードをシステムに保存します。

実行可能な展開計画

<オル>

テナントの分離から始める: 高度な課金機能を追加する前に、顧客、ワークスペース、キー、プラン、および制限レコードを実装します。

プリフライト強制の構築: ルーティング前に、取り消されたキー、請求の一時停止、許可されていないモデル、トラフィックの超過をブロックします。

使用状況台帳を作成します。 リクエスト ID、トークン数、コスト、再販価格、ステータス、タイムスタンプ、冪等キーを記録します。

調整の追加: 請求前に内部使用量と上流プロバイダの合計を比較します。

請求概要の同期: 安定した顧客マッピングとべき等キーを使用して、日次または時間ごとの集計を請求プラットフォームに送信します。

Wire Telegram アラート: 残高不足、停止、キー ローテーション、サポート エスカレーション メッセージから始まります。

分離テストを実行する: どの顧客も別の顧客のキー、使用状況、制限、請求書、チャットのメタデータにアクセスできないことを確認します。

再販業者ポータルは、AI API の単なるラッパーではありません。これは、認証、テナント ポリシー、使用状況分析、請求、サポートのためのオペレーティング層です。まず元帳と制限を構築し、アップストリーム キーをサーバー側に保持し、顧客向けのすべてのキーを取り消し可能、範囲指定可能、および帰属可能にします。

関連資料

• API キーの分離とローテーション実践
• AI API コスト管理テクニック
• 障害認識ルーティングと再試行