Partner API 個のエンドポイント
キー、グループ、リクエスト、トランザクションの Partner API 件のリクエストとレスポンスの例を完了します。
Partner API 個のエンドポイント
ベース URL:
https://p-api.model-gate.comすべてのリクエストには以下が必要です。
Authorization: Bearer mg_partner_...
Accept: application/jsonすべての金額および制限値は JSON 10 進数文字列です。これらを 2 進浮動小数点数として解析しないでください。
共通銀行統合ルール
すべての外部タイムスタンプは UTC RFC3339 です。収集エンドポイントの使用 limit (1 ～ 100) プラス不透明 cursor;カーソルの内容を決して解析したり作成したりしないでください。 POST、 PATCH、 そして DELETE リクエストには必要な Idempotency-Key;タイムアウト後に同じキーを使用して同じ操作を再試行します。冪等性レコードは 7 日間保持されます。応答には次のものが含まれます X-Request-ID、 は Cache-Control: no-store、すべてのエラーは JSON です。レート制限応答は HTTP です 429 と Retry-After そして X-RateLimit-* ヘッダー。不明な本文/クエリフィールドは拒否されます。
機械可読な OpenAPI 3.1 コントラクトは、次のように配布されます。 resources/contracts/partner-api.openapi.yaml。
APIキーを作成する
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/keys \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \
-H "Content-Type: application/json" \
-d '{
"name": "Telegram user 123",
"group_id": "GROUP_PUBLIC_ID",
"rpm_limit": 30,
"concurrency_limit": 2,
"spend_limit": "20.0000000000",
"usage_price_basis": "official_price",
"usage_price_multiplier": "0.900000"
}'応答 — 201
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"group_id": "GROUP_PUBLIC_ID",
"name": "Telegram user 123",
"key_prefix": "mg_live_ab12",
"key": "mg_live_ab12...",
"status": "active",
"rpm_limit": 30,
"concurrency_limit": 2,
"spend_limit": "20.0000000000",
"usage": "0.0000000000",
"total_spent": "0.0000000000",
"usage_price_basis": "official_price",
"usage_price_multiplier": "0.900000",
"effective_usage_price_basis": "official_price",
"effective_usage_price_multiplier": "0.900000"
}
}完全な key value は、作成または回転後にのみ返されます。
API キーのリストを表示する
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/keys \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": [
{
"public_id": "KEY_PUBLIC_ID",
"group_id": "GROUP_PUBLIC_ID",
"name": "Telegram user 123",
"status": "active",
"spend_limit": "20.0000000000",
"usage": "3.2500000000",
"total_spent": "1.1400000000"
}
]
}リストは新しいものから順に並べられ、不透明なカーソルのページネーションを使用します。合格 limit=1..100;いつ meta.has_more 本当です、送信します meta.next_cursor 次として cursor。
APIキーを1つ取得する
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"group_id": "GROUP_PUBLIC_ID",
"name": "Telegram user 123",
"status": "active",
"rpm_limit": 30,
"concurrency_limit": 2,
"spend_limit": "20.0000000000",
"usage": "3.2500000000",
"total_spent": "1.1400000000",
"effective_usage_price_basis": "official_price",
"effective_usage_price_multiplier": "0.900000"
}
}APIキーを更新する
PATCH サポートされている変更可能な値のみを置き換えます。グループからキーを削除するには、空のキーを送信します。 group_id。評価設定を継承するには、 null キーレベルの基底と乗数の場合。
リクエスト
curl -X PATCH https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated user name",
"group_id": "GROUP_PUBLIC_ID",
"rpm_limit": 60,
"concurrency_limit": 4,
"spend_limit": "40.0000000000",
"usage_price_basis": null,
"usage_price_multiplier": null
}'応答 — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"spend_limit": "40.0000000000",
"usage": "3.2500000000",
"effective_usage_price_basis": "user_price",
"effective_usage_price_multiplier": "1.000000"
}
}APIキーを削除する
リクエスト
curl -X DELETE https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答 — 200
{"data":{"deleted":true}}キーの凍結と凍結解除
凍結リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/freeze \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \フリーズ応答
{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}凍結解除リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/unfreeze \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答の凍結解除
{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}凍結を解除するには、確認済みの所有者の電子メールが必要です。
キーを回転させる
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/rotate \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答 — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"status": "active",
"key_prefix": "mg_live_cd34",
"key": "mg_live_cd34..."
}
}キーの使用状況をリセットする
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/reset-usage \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答 — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"usage": "0.0000000000",
"total_spent": "1.1400000000"
}
}使用量をリセットしても、生涯の支出やアカウント残高は変更されません。
キーの使用状況を取得する
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"usage": "3.2500000000",
"total_spent": "1.1400000000"
}
}使用量制限と残りの使用量を取得する
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"spend_limit": "20.0000000000",
"usage": "3.2500000000",
"remaining": "16.7500000000"
}
}いつ spend_limit ゼロ、無制限、そして remaining は null。
キーの最新のリクエストを取得する
詳細なリクエスト履歴は、によって制御されるホット保持データセットです。 API_REQUESTS_HOT_RETENTION_DAYS (デフォルトは 7 日)。応答メタデータは、アクティブな保存期間を報告します。長期的な財務調整には残高トランザクションを使用します。
limit はオプションで、デフォルトは 10 で、1 ～ 100 の整数である必要があります。最終的なリクエストは次の順序で並べられます。 finished_at 最新のものから。いつ meta.has_more は true、 合格 meta.next_cursor 不透明なものとして before クエリパラメータを使用して、次に古いページを取得します。自分でカーソルを解析したり構築したりしないでください。
応答には、移行後に完了したリクエストに対する不変のユーザーおよび公式の 100 万あたりのトークン レートが含まれます 059_request_pricing_audit_snapshot.sql。計算もしてくれます pricing_snapshot.usage_price 別のレートセットを保存せずに、保存されたベーシス、乗数、および履歴レートから。これにより、カタログ価格が変更された後に、独立した使用制限評価が監査可能になります。移行 059 が戻る前に作成されたリクエストの履歴 pricing_snapshot.available: false 現在の価格を置き換えるのではなく、 Claude/OpenAI 互換のバッチ API を通じて実行されたリクエストは、明示的に でマークされます。 request_mode: "batch" プロトコル、バッチ ジョブ ID、 custom_id、およびスナップショットされた Model Gate のバッチ価格乗数。
レイテンシは安定したビジネス/パートナー名を使用します。 gateway_overhead_ms、 upstream_first_token_ms、 そして e2e_first_token_ms。 E2E の最初のトークンの値は、Model Gate リクエストの開始から最初の実際のコンテンツ トークンまで測定され、クライアント側のネットワーク/TLS 時間は含まれません。 Partner API は明示的なもののみを公開します e2e_first_token_ms 名前;内部ストレージ列は残ります api_requests.first_token_ms。
リクエスト
curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": [
{
"request_id": "01KZ...",
"key_id": "KEY_PUBLIC_ID",
"group_id": "GROUP_PUBLIC_ID",
"model": "claude-opus-4.7",
"endpoint": "messages",
"method": "POST",
"status": "succeeded",
"status_code": 200,
"is_stream": false,
"request_mode": "batch",
"batch": {
"protocol": "claude",
"job_id": "msgbatch_01K...",
"custom_id": "request-1",
"price_multiplier": "0.5"
},
"tokens": {
"input": 120,
"output": 45,
"cached": 0,
"cache_write": 0,
"reasoning": 0,
"total": 165
},
"cost": "0.0000345",
"usage_cost": "0.00345",
"official_base_cost": "0.000345",
"currency": "USD",
"usage_pricing": {
"basis": "official_price",
"base_field": "official_base_cost",
"base_amount": "0.000345",
"multiplier": "10",
"usage_cost": "0.00345",
"formula": "round(base_amount * multiplier, 10)"
},
"pricing_snapshot": {
"available": true,
"unit": "per_1m_tokens",
"user_price": {
"input": "0.2",
"output": "1",
"cache_read": "0.02",
"cache_write": "0.25",
"reasoning": "1"
},
"official_price": {
"input": "1",
"output": "5",
"cache_read": "0.1",
"cache_write": "1.25",
"reasoning": "5"
},
"usage_price": {
"input": "10",
"output": "50",
"cache_read": "1",
"cache_write": "12.5",
"reasoning": "50"
}
},
"duration_ms": 842,
"gateway_overhead_ms": 34,
"upstream_first_token_ms": 156,
"e2e_first_token_ms": 190,
"settlement_status": "settled",
"started_at": "2026-08-05T10:00:00Z",
"finished_at": "2026-08-05T10:00:00.842Z"
}
],
"meta": {
"key_id": "KEY_PUBLIC_ID",
"limit": 10,
"returned": 1,
"order": "finished_at_desc",
"next_cursor": "eyJ0IjoiMjAyNi0wOC0wNSAxMDowMDowMCIsInAiOiIwMUt...",
"has_more": true
}
}次の古いページに進むには:
curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10&before=NEXT_CURSOR" \
-H "Authorization: Bearer mg_partner_..."無効な before カーソルはHTTPを返します 422。カーソルには、終了時刻の位置と外部リクエストのパブリック ID のみが含まれます。内部の数値リクエスト ID が公開されることはありません。
同期リクエストとネイティブ非同期リクエストの場合、 request_mode は sync または async そして batch オブジェクトは省略されています。保存されたトークンレートのスナップショットにより、過去の基本計算を次のように再現できます。 sum(tokens × snapshotted_rate / 1,000,000)。決済では、選択した基準金額を小数点第10位に四捨五入して計算します。 round(base_amount × multiplier, 10)。保存されている cost、 official_base_cost、 そして usage_cost フィールドは引き続き権限を持ちます。
このエンドポイントから生のリクエストおよびレスポンスの本文が返されることはありません。
残高トランザクションをリストする
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/transactions \
-H "Authorization: Bearer mg_partner_..."応答 — 200
{
"data": [
{
"transaction_id": "TRANSACTION_PUBLIC_ID",
"type": "debit",
"source": "api_usage_minute",
"billing_minute_num": 29769120,
"amount": "-0.0232000000",
"request_count": 100,
"balance_before": null,
"balance_after": null,
"api_key_id": null,
"created_at": "2026-08-05T10:00:00Z"
}
]
}請求可能な推論は、請求所有者および終了時間分ごとに 1 つのウォレット台帳行として表されます。 transaction_id 永続的な公開台帳の識別子です。 request_count その分の引き落としに含まれるリクエストの数です。 billing_minute_num は floor(unix(finished_at)/60)。生の内部台帳 id / source_id 値は返されません。 API 使用量の集計行が意図的に返される null のために balance_before、 balance_after、 そして api_key_id;正確なキー/グループ/リクエストの詳細は、リクエスト履歴とパネルの分ドリルダウンから引き続き利用できます。
現在の残高を取得する
curl https://p-api.model-gate.com/api/v1/partner/balance \
-H "Authorization: Bearer mg_partner_..."{"data":{"balance":"1234.5678900000","currency":"USD","as_of":"2026-08-28T07:00:00Z"}}このエンドポイントは次の後に使用します。 account.balance_low コールバックを使用して、モデル API 認証情報を必要とせずに現在のアカウントのウォレットを調整します。
パートナー監査イベントのリストを表示する
curl "https://p-api.model-gate.com/api/v1/partner/audit-events?limit=100" \
-H "Authorization: Bearer mg_partner_..."監査イベントは、成功したパートナー管理の変更をリクエスト ID、アクション、ターゲット、ソース IP、ステータス、安全なメタデータ、および UTC タイムスタンプとともに記録します。シークレット、ベアラー トークン、API キー プレーンテキスト、冪等キー、リクエスト フィンガープリント、およびリプレイ本文は、監査メタデータには保存されません。使用 cursor 後続のページおよびオプション action フィルタリング。
グループを作成する
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/groups \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \
-H "Content-Type: application/json" \
-d '{
"name": "Telegram bot A",
"description": "Keys created by bot A",
"rpm_limit": 100,
"concurrency_limit": 20,
"spend_limit": "1000.0000000000",
"usage_price_basis": "official_price",
"usage_price_multiplier": "0.900000"
}'応答 — 201
{
"data": {
"public_id": "GROUP_PUBLIC_ID",
"name": "Telegram bot A",
"status": "active",
"spend_limit": "1000.0000000000",
"usage": "0.0000000000",
"total_spent": "0.0000000000",
"usage_price_basis": "official_price",
"usage_price_multiplier": "0.900000"
}
}リストグループ
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/groups \
-H "Authorization: Bearer mg_partner_..."応答
{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}グループを取得または更新する
リクエストの取得
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."応答を取得する
{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}更新リクエスト
curl -X PATCH https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \
-H "Content-Type: application/json" \
-d '{"name":"Telegram bot A production","status":"active","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}'応答を更新する
{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A production","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}}グループを削除する
空でないグループは削除されません。まずすべてのメンバー API キーを移動または削除します。それ以外の場合、API は HTTP を返します。 409 と group_not_empty。
リクエスト
curl -X DELETE https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答
{"data":{"deleted":true}}キーは、データベースの外部キーの動作に従って切り離されます。削除する前にメンバーシップを確認してください。
グループの使用状況をリセットする
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/reset-usage \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答
{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}グループメンバーをリストする
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
-H "Authorization: Bearer mg_partner_..."応答
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}グループにキーを追加する
リクエスト
curl -X POST https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \
-H "Content-Type: application/json" \
-d '{"key_id":"KEY_PUBLIC_ID"}'応答
応答は、更新されたグループ メンバー リストです。
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active"}]}グループからキーを削除する
リクエスト
curl -X DELETE https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..." \
-H "Idempotency-Key: operation-unique-001" \応答
{"data":{"removed":true}}グループ使用量を取得する
リクエスト
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."応答
{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}グループ統計を取得する
from そして to 次で終わる UTC RFC3339 タイムスタンプのみを受け入れます Z (6 桁までの小数秒が許可されます)。統計は、次のキーを持つ完了したリクエストの集計からのみ計算されます。 finished_at;現在開いている分は意図的に除外されているため、結果は最大 1 分間の集計リズムまで遅れる可能性があります。
average_duration_ms 平均の完全な Model Gate リクエスト期間 (duration_ms) 選択した期間内に完了したリクエスト全体。これは、E2E のファースト トークン レイテンシ、アップストリームのファースト トークン レイテンシ、またはゲートウェイ オーバーヘッドではありません。 Partner API は、この明示的なメトリック名のみを公開します。
リクエスト
curl "https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/stats?from=2026-08-01T00:00:00Z&to=2026-08-05T23:59:59Z" \
-H "Authorization: Bearer mg_partner_..."応答
{
"data": {
"group_id": "GROUP_PUBLIC_ID",
"requests": 120,
"errors": 3,
"input_tokens": 50000,
"output_tokens": 12000,
"cached_tokens": 8000,
"cache_write_tokens": 1200,
"reasoning_tokens": 2000,
"cost": "8.5000000000",
"average_duration_ms": "842.50",
"from": "2026-08-01T00:00:00Z",
"to": "2026-08-05T23:59:59Z"
}
}非同期結果を取得する
リクエスト
curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
-H "Authorization: Bearer mg_partner_..."応答の処理中
{
"data": {
"request_id": "01KZ...",
"status": "processing",
"created_at": "2026-08-05T10:00:00Z",
"started_at": "2026-08-05T10:00:00Z",
"completed_at": null,
"expires_at": "2026-08-06T10:00:00Z"
}
}完了した応答
{
"data": {
"request_id": "01KZ...",
"status": "completed",
"response_status": 200,
"response_headers": {"Content-Type":"application/json"},
"response": {"id":"resp_example","status":"completed"},
"completed_at": "2026-08-05T10:00:05Z",
"expires_at": "2026-08-06T10:00:00Z"
}
}よくあるエラー
無効な Partner API キー — 401
{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}リソースが見つかりません — 404
{"error":{"type":"not_found","message":"API key not found"}}無効なリクエスト — 422
{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}Partner API 個の JSON 本文の変更は 1 MiB に制限されます。
べき等性の競合 — 409
同じ Idempotency-Key 別のリクエストに再利用されました。新しい論理演算用の新しいキーを生成します。
レート制限 — 429
応答には次の内容が含まれます error.code = partner_rate_limit_exceeded そして Retry-After。示された遅延が経過した後にのみ再試行してください。
メソッドは許可されていません — 405
パートナー ホストが JSON エラーと HTTP を返します。 Allow ヘッダ; HTML エラー ページに戻ることはありません。
ビジネス資格情報の主要ルール
ビジネス Partner API トークンの場合、検証された組織の所有者のみが受け入れられます。 Partner API を通じて作成されたキーは、その所有者を請求所有者と資格情報プリンシパルの両方として使用します。従業員と校長の割り当ては、Web パネルで実行されます。 group_idを指定する場合は、ビジネス アカウントが所有するアクティブなグループを識別する必要があります。無効な値は HTTP を返します 422 グループ化されていないキーにフォールバックすることはありません。リクエスト履歴の応答には以下が含まれる場合があります principal_user_id 請求の所有権から独立して資格情報のプリンシパルを識別します。