Partner API endpoint

URL di base:

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

Tutte le richieste richiedono:

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

Tutti i valori monetari e limite sono stringhe decimali JSON. Non analizzarli come numeri binari a virgola mobile.

Regole comuni di integrazione bancaria

Tutti i timestamp esterni sono UTC RFC3339. Utilizzo degli endpoint di raccolta limit (1–100) più un opaco cursor; non analizzare o produrre mai il contenuto del cursore. POST, PATCH, E DELETE le richieste richiedono Idempotency-Key; ripetere la stessa operazione con lo stesso tasto dopo il timeout. I record di idempotenza vengono conservati per 7 giorni. Le risposte includono X-Request-ID, Sono Cache-Control: no-storee tutti gli errori sono JSON. Le risposte al limite di velocità sono HTTP 429 con Retry-After E X-RateLimit-* intestazioni. I campi del corpo/query sconosciuti vengono rifiutati.

Il contratto OpenAPI 3.1 leggibile dalla macchina è distribuito come resources/contracts/partner-api.openapi.yaml.

Crea una chiave API

Richiesta

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

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

Il completo key il valore viene restituito solo dopo la creazione o la rotazione.

Elenca le chiavi API

Richiesta

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

Risposta: 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"
    }
  ]
}

L'elenco viene ordinato per primo dal più recente e utilizza l'impaginazione del cursore opaco. Passaggio limit=1..100; Quando meta.has_more è vero, invia meta.next_cursor come il successivo cursor.

Ottieni una chiave API

Richiesta

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

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

Aggiorna una chiave API

PATCH sostituisce solo i valori modificabili supportati. Per rimuovere la chiave da un gruppo, invia un messaggio vuoto group_id. Per ereditare le impostazioni di valutazione, inviare null per la base e il moltiplicatore a livello di chiave.

Richiesta

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

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

Elimina una chiave API

Richiesta

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

Risposta: 200

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

Congelare e sbloccare una chiave

Richiesta di congelamento

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

Blocca la risposta

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

Richiesta di sblocco

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

Sblocca la risposta

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

Lo sblocco richiede un indirizzo email del proprietario verificato.

Ruota una chiave

Richiesta

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

Risposta: 200

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

Reimposta l'utilizzo della chiave

Richiesta

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

Risposta: 200

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

La reimpostazione dell'utilizzo non modifica la spesa totale o il saldo dell'account.

Ottieni l'utilizzo della chiave

Richiesta

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

Risposta: 200

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

Ottieni il limite di spesa e l'utilizzo rimanente

Richiesta

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

Risposta: 200

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

Quando spend_limit è zero, è illimitato e remaining È null.

Ricevi le ultime richieste per una chiave

La cronologia dettagliata delle richieste è un set di dati di conservazione a caldo controllato da API_REQUESTS_HOT_RETENTION_DAYS (predefinito 7 giorni). I metadati della risposta segnalano la finestra di conservazione attiva. Utilizzare le transazioni di saldo per la riconciliazione finanziaria a lungo termine.

limit è facoltativo, il valore predefinito è 10 e deve essere un numero intero compreso tra 1 e 100. Le richieste finalizzate vengono ordinate per finished_at prima il più recente. Quando meta.has_more È true, passaggio meta.next_cursor come l'opaco before parametro di query per recuperare la pagina successiva più vecchia. Non analizzare o costruire manualmente i cursori.

La risposta contiene tariffe per utenti immutabili e ufficiali per milione di token per le richieste completate dopo la migrazione 059_request_pricing_audit_snapshot.sql. Inoltre calcola pricing_snapshot.usage_price dalla base salvata, dal moltiplicatore e dai tassi storici senza memorizzare un altro set di tassi. Ciò rende verificabile la valutazione indipendente del limite di utilizzo dopo la modifica dei prezzi di catalogo. Richieste storiche create prima della migrazione 059 restituite pricing_snapshot.available: false rather than substituting current prices. Le richieste eseguite tramite API batch compatibili con Claude/OpenAI sono esplicitamente contrassegnate con request_mode: "batch" e includere il protocollo, l'ID del lavoro batch, custom_ide il moltiplicatore del prezzo batch Model Gate istantaneamente.

La latenza utilizza nomi di aziende/partner stabili: gateway_overhead_ms, upstream_first_token_ms, E e2e_first_token_ms. Il valore del primo token E2E viene misurato dall'inizio della richiesta Model Gate al primo token di contenuto reale ed esclude il tempo di rete/TLS lato client. Il Partner API espone solo l'esplicito e2e_first_token_ms nome; rimane la colonna di memoria interna api_requests.first_token_ms.

Richiesta

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

Risposta: 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
  }
}

Per continuare con la pagina successiva più vecchia:

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 invalido before il cursore restituisce HTTP 422. Il cursore contiene solo la posizione dell'ora di fine e l'ID pubblico della richiesta esterna; gli ID di richiesta numerici interni non vengono mai esposti.

Per le richieste sincrone e asincrone native, request_mode È sync O async e il batch l'oggetto viene omesso. L'istantanea della velocità del token salvata consente di riprodurre il calcolo della base storica come sum(tokens × snapshotted_rate / 1,000,000). La liquidazione arrotonda l'importo base selezionato a 10 cifre decimali e quindi calcola round(base_amount × multiplier, 10). Il memorizzato cost, official_base_cost, E usage_cost i campi rimangono autorevoli.

I corpi delle richieste e delle risposte non elaborate non vengono mai restituiti da questo endpoint.

Elenca le transazioni del saldo

Richiesta

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

Risposta: 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'inferenza fatturabile è rappresentata come una riga nel registro del portafoglio per titolare della fatturazione e minuto di fine. transaction_id è l'identificatore durevole del registro pubblico. request_count è il numero di richieste incluse in quel minuto di addebito; billing_minute_num È floor(unix(finished_at)/60). Registro interno grezzo id / source_id i valori non vengono restituiti. Le righe aggregate sull'utilizzo dell'API vengono restituite intenzionalmente null per balance_before, balance_after, E api_key_id; i dettagli esatti di chiave/gruppo/richiesta rimangono disponibili dalla cronologia delle richieste e dal dettaglio dettagliato dei minuti del pannello.

Ottieni il saldo attuale

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

Utilizza questo endpoint dopo account.balance_low callback per riconciliare il portafoglio del conto corrente senza richiedere una credenziale Model API.

Elenca gli eventi di controllo dei partner

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

Gli eventi di controllo registrano le mutazioni di gestione dei partner riuscite con ID richiesta, azione, destinazione, IP di origine, stato, metadati sicuri e timestamp UTC. I segreti, i token di connessione, il testo in chiaro della chiave API, le chiavi di idempotenza, le impronte digitali delle richieste e i corpi di riproduzione non vengono archiviati nei metadati di controllo. Utilizzo cursor per le pagine successive e facoltativo action filtraggio.

Crea un gruppo

Richiesta

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

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

Elenca i gruppi

Richiesta

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

Risposta

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

Ottieni o aggiorna un gruppo

Ottieni la richiesta

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

Ottieni risposta

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

Richiesta di aggiornamento

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

Aggiorna la risposta

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

Elimina un gruppo

Un gruppo non vuoto non viene eliminato. Sposta o elimina prima tutte le chiavi API dei membri; in caso contrario l'API restituisce HTTP 409 con group_not_empty.

Richiesta

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

Risposta

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

Le chiavi vengono scollegate in base al comportamento della chiave esterna del database. Verificare l'appartenenza prima dell'eliminazione.

Reimposta l'utilizzo del gruppo

Richiesta

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

Risposta

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

Elenca i membri del gruppo

Richiesta

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

Risposta

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

Aggiungi una chiave a un gruppo

Richiesta

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

Risposta

La risposta è l'elenco aggiornato dei membri del gruppo:

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

Rimuovere una chiave da un gruppo

Richiesta

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

Risposta

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

Ottieni l'utilizzo del gruppo

Richiesta

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

Risposta

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

Ottieni statistiche di gruppo

from E to accetta solo timestamp UTC RFC3339 che terminano con Z (sono consentite frazioni di secondo fino a 6 cifre). Le statistiche vengono calcolate solo dagli aggregati di richieste completate digitate da finished_at; il minuto attualmente aperto è intenzionalmente escluso, pertanto i risultati potrebbero subire ritardi fino alla cadenza di aggregazione dei minuti.

average_duration_ms è la durata media della richiesta completa di Model Gate (duration_ms) tra le richieste completate nel periodo selezionato. Non si tratta della latenza del primo token E2E, della latenza del primo token upstream o dell'overhead del gateway. Il Partner API espone solo questo nome di metrica esplicito.

Richiesta

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

Risposta

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

Ottieni un risultato asincrono

Richiesta

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

Risposta in elaborazione

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

Risposta completata

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

Errori comuni

Chiave Partner API non valida: 401

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

Risorsa non trovata — 404

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

Richiesta non valida — 422

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

Partner API corpi JSON mutanti sono limitati a 1 MiB.

Conflitto di idempotenza — 409

Lo stesso Idempotency-Key è stato riutilizzato per una richiesta diversa. Genera una nuova chiave per una nuova operazione logica.

Limite di tariffa: 429

La risposta contiene error.code = partner_rate_limit_exceeded E Retry-After. Riprovare solo dopo il ritardo indicato.

Metodo non consentito - 405

L'host partner restituisce un errore JSON più l'HTTP Allow intestazione; non ritorna mai a una pagina di errore HTML.

Regole principali delle credenziali aziendali

Per un token aziendale n. {0}, è accettato solo il proprietario dell'organizzazione verificato. Le chiavi create tramite Partner API utilizzano tale proprietario sia come proprietario della fatturazione che come entità credenziale. L'assegnazione del rapporto dipendente-preside viene eseguita nel pannello web. group_id, quando fornito, deve identificare un gruppo attivo facente capo all'account Business; i valori non validi restituiscono HTTP 422 e non ricorrere mai a una chiave non raggruppata. Le risposte alla cronologia delle richieste possono includere principal_user_id per identificare l'entità credenziale indipendentemente dalla proprietà della fatturazione.