Partner API points de terminaison

URL de base :

https://p-api.model-gate.com

Toutes les demandes nécessitent :

Authorization: Bearer mg_partner_...
Accept: application/json

Toutes les valeurs monétaires et limites sont des chaînes décimales JSON. Ne les analysez pas comme des nombres binaires à virgule flottante.

Règles communes d'intégration de la Banque

Tous les horodatages externes sont UTC RFC3339. Utilisation des points de terminaison de collecte limit (1–100) plus un opaque cursor; ne jamais analyser ou fabriquer le contenu du curseur. POST, PATCH, et DELETE les demandes nécessitent Idempotency-Key; réessayez la même opération avec la même clé après les délais d'attente. Les dossiers d'idempotence sont conservés pendant 7 jours. Les réponses incluent X-Request-ID, sont Cache-Control: no-store, et toutes les erreurs sont JSON. Les réponses à limite de débit sont HTTP 429 avec Retry-After et X-RateLimit-* en-têtes. Les champs de corps/requête inconnus sont rejetés.

Le contrat OpenAPI 3.1 lisible par machine est distribué sous la forme resources/contracts/partner-api.openapi.yaml.

Créer une clé API

Demande

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"
  }'

Réponse — 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"
  }
}

Le complet key la valeur n'est renvoyée qu'après la création ou la rotation.

Répertorier les clés API

Demande

curl https://p-api.model-gate.com/api/v1/partner/keys \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 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"
    }
  ]
}

La liste est classée en premier et utilise une pagination de curseur opaque. Passer limit=1..100; quand meta.has_more c'est vrai, envoie meta.next_cursor comme le prochain cursor.

Obtenez une clé API

Demande

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 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"
  }
}

Mettre à jour une clé API

PATCH remplace uniquement les valeurs mutables prises en charge. Pour supprimer la clé d'un groupe, envoyez un message vide group_id. Pour hériter des paramètres de valorisation, envoyez null pour la base de niveau clé et le multiplicateur.

Demande

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
  }'

Réponse — 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"
  }
}

Supprimer une clé API

Demande

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" \

Réponse — 200

{"data":{"deleted":true}}

Geler et débloquer une clé

Demande de gel

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" \

Geler la réponse

{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}

Demande de dégel

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" \

Dégeler la réponse

{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}

Le dégel nécessite une adresse e-mail de propriétaire vérifiée.

Faire pivoter une clé

Demande

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" \

Réponse — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "status": "active",
    "key_prefix": "mg_live_cd34",
    "key": "mg_live_cd34..."
  }
}

Réinitialiser l'utilisation de la clé

Demande

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" \

Réponse — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "usage": "0.0000000000",
    "total_spent": "1.1400000000"
  }
}

La réinitialisation de l'utilisation ne modifie pas les dépenses à vie ni le solde du compte.

Obtenir l'utilisation des clés

Demande

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 200

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "usage": "3.2500000000",
    "total_spent": "1.1400000000"
  }
}

Obtenez la limite de dépenses et l'utilisation restante

Demande

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 200

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "spend_limit": "20.0000000000",
    "usage": "3.2500000000",
    "remaining": "16.7500000000"
  }
}

Quand spend_limit est nul, il est illimité et remaining est null.

Recevez les dernières demandes de clé

L'historique détaillé des demandes est un ensemble de données de conservation à chaud contrôlé par API_REQUESTS_HOT_RETENTION_DAYS (par défaut 7 jours). Les métadonnées de réponse indiquent la fenêtre de rétention active. Utilisez les transactions de solde pour un rapprochement financier à plus long terme.

limit est facultatif, la valeur par défaut est 10 et doit être un nombre entier compris entre 1 et 100. Les demandes finalisées sont classées par finished_at le plus récent en premier. Quand meta.has_more est true, passer meta.next_cursor comme l'opaque before paramètre de requête pour récupérer la page la plus ancienne suivante. N'analysez pas et ne construisez pas de curseurs vous-même.

La réponse contient des taux d'utilisateurs immuables et des taux officiels par million de jetons pour les demandes terminées après la migration. 059_request_pricing_audit_snapshot.sql. Il calcule également pricing_snapshot.usage_price à partir de la base enregistrée, du multiplicateur et des taux historiques sans stocker un autre ensemble de taux. Cela rend l'évaluation indépendante de la limite d'utilisation vérifiable après la modification des prix catalogue. Historique des demandes créées avant le retour de la migration 059 pricing_snapshot.available: false plutôt que de remplacer les prix actuels. Les requêtes exécutées via les API batch compatibles Claude/OpenAI sont explicitement marquées par request_mode: "batch" et inclure leur protocole, l'ID du travail par lots, custom_id, et le multiplicateur de prix de lot Model Gate instantané.

La latence utilise des noms d'entreprise/partenaire stables : gateway_overhead_ms, upstream_first_token_ms, et e2e_first_token_ms. La valeur du premier jeton E2E est mesurée à partir du début de la demande Model Gate jusqu'au premier jeton de contenu réel et exclut le temps réseau/TLS côté client. Le Partner API expose uniquement le explicite e2e_first_token_ms nom; la colonne de stockage interne reste api_requests.first_token_ms.

Demande

curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 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
  }
}

Pour continuer avec la page suivante plus ancienne :

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_..."

Un invalide before le curseur renvoie HTTP 422. Le curseur contient uniquement la position d'heure de fin et l'ID public de la demande externe ; les identifiants de requêtes numériques internes ne sont jamais exposés.

Pour les requêtes asynchrones synchrones et natives, request_mode est sync ou async et le batch l'objet est omis. L'instantané du taux de jeton enregistré permet de reproduire le calcul de base historique sous forme de sum(tokens × snapshotted_rate / 1,000,000). Le règlement arrondit le montant de base sélectionné à 10 décimales, puis calcule round(base_amount × multiplier, 10). Le stocké cost, official_base_cost, et usage_cost les champs restent faisant autorité.

Les corps bruts de requête et de réponse ne sont jamais renvoyés par ce point de terminaison.

Répertorier les transactions de solde

Demande

curl https://p-api.model-gate.com/api/v1/partner/transactions \
  -H "Authorization: Bearer mg_partner_..."

Réponse — 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"
    }
  ]
}

L'inférence facturable est représentée par une ligne du grand livre du portefeuille par propriétaire de facturation et par minute d'heure de fin. transaction_id est l’identifiant durable du grand livre public. request_count est le nombre de demandes incluses dans ce débit minute ; billing_minute_num est floor(unix(finished_at)/60). Grand livre interne brut id / source_id les valeurs ne sont pas renvoyées. Les lignes d'utilisation de l'API agrégées sont intentionnellement renvoyées null pour balance_before, balance_after, et api_key_id; Les détails exacts de la clé/du groupe/de la demande restent disponibles à partir de l’historique des demandes et de l’exploration des minutes du panneau.

Obtenez le solde actuel

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"}}

Utilisez ce point de terminaison après account.balance_low rappels pour rapprocher le portefeuille du compte actuel sans nécessiter d'informations d'identification de l'API modèle.

Répertorier les événements d'audit des partenaires

curl "https://p-api.model-gate.com/api/v1/partner/audit-events?limit=100" \
  -H "Authorization: Bearer mg_partner_..."

Les événements d'audit enregistrent les mutations réussies de la gestion des partenaires avec l'ID de demande, l'action, la cible, l'adresse IP source, le statut, les métadonnées sécurisées et l'horodatage UTC. Les secrets, les jetons du porteur, le texte brut des clés API, les clés d'idempotence, les empreintes digitales des demandes et les corps de relecture ne sont pas stockés dans les métadonnées d'audit. Utiliser cursor pour les pages suivantes et en option action filtration.

Créer un groupe

Demande

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"
  }'

Réponse — 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"
  }
}

Liste des groupes

Demande

curl https://p-api.model-gate.com/api/v1/partner/groups \
  -H "Authorization: Bearer mg_partner_..."

Réponse

{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}

Obtenir ou mettre à jour un groupe

Obtenir la demande

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Obtenir une réponse

{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}

Demande de mise à jour

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"}'

Mettre à jour la réponse

{"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"}}

Supprimer un groupe

Un groupe non vide n'est pas supprimé. Déplacez ou supprimez d'abord toutes les clés API des membres ; sinon l'API renvoie HTTP 409 avec group_not_empty.

Demande

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" \

Réponse

{"data":{"deleted":true}}

Les clés sont détachées en fonction du comportement des clés étrangères de la base de données. Vérifiez l’adhésion avant la suppression.

Réinitialiser l'utilisation du groupe

Demande

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" \

Réponse

{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}

Répertorier les membres du groupe

Demande

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
  -H "Authorization: Bearer mg_partner_..."

Réponse

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}

Ajouter une clé à un groupe

Demande

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"}'

Réponse

La réponse est la liste mise à jour des membres du groupe :

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active"}]}

Supprimer une clé d'un groupe

Demande

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" \

Réponse

{"data":{"removed":true}}

Obtenir une utilisation en groupe

Demande

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Réponse

{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}

Obtenez des statistiques de groupe

from et to accepter uniquement les horodatages UTC RFC3339 se terminant par Z (les fractions de seconde jusqu'à 6 chiffres sont autorisées). Les statistiques sont calculées uniquement à partir des agrégats de demandes complétées saisis par finished_at; la minute actuellement ouverte est intentionnellement exclue, de sorte que les résultats peuvent être en retard d'une cadence d'agrégation allant jusqu'à la minute.

average_duration_ms est la durée moyenne complète de la demande Model Gate (duration_ms) sur les demandes terminées au cours de la période sélectionnée. Il ne s’agit pas de latence du premier jeton E2E, de latence du premier jeton en amont ou de surcharge de passerelle. Le Partner API expose uniquement ce nom de métrique explicite.

Demande

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_..."

Réponse

{
  "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"
  }
}

Obtenez un résultat asynchrone

Demande

curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
  -H "Authorization: Bearer mg_partner_..."

Réponse au traitement

{
  "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"
  }
}

Réponse complétée

{
  "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"
  }
}

Erreurs courantes

Clé Partner API non valide – 401

{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}

Ressource introuvable — 404

{"error":{"type":"not_found","message":"API key not found"}}

Demande invalide — 422

{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}

Partner API corps JSON en mutation sont limités à 1 Mio.

Conflit d'idempotence — 409

Le même Idempotency-Key a été réutilisé pour une demande différente. Générez une nouvelle clé pour une nouvelle opération logique.

Limite de taux – 429

La réponse contient error.code = partner_rate_limit_exceeded et Retry-After. Réessayez seulement après le délai indiqué.

Méthode non autorisée — 405

L'hôte partenaire renvoie une erreur JSON plus le HTTP Allow en-tête ; il ne revient jamais à une page d'erreur HTML.

Règles principales des titres de compétences professionnels

Pour un jeton d'entreprise n° {0}, seul le propriétaire de l'organisation vérifiée est accepté. Les clés créées via Partner API utilisent ce propriétaire à la fois comme propriétaire de facturation et comme principal d'identification. L'affectation employé-principal est effectuée dans le panneau Web. group_id, une fois fourni, doit identifier un groupe actif appartenant au compte Business ; les valeurs non valides renvoient HTTP 422 et ne revenez jamais à une clé non groupée. Les réponses de l'historique des demandes peuvent inclure principal_user_id pour identifier le principal des informations d'identification indépendamment de la propriété de facturation.