B2BB2B LLM

Partner API puncte finale

Completează Partner API exemple de solicitare și răspuns pentru chei, grupuri, solicitări și tranzacții.

Partner API puncte finale

Adresa URL de bază:

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

Toate cererile necesită:

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

Toate valorile monetare și limită sunt șiruri zecimale JSON. Nu le analizați ca numere binare în virgulă mobilă.

Reguli comune de integrare a Băncii

Toate marcajele orare externe sunt UTC RFC3339. Utilizarea punctelor finale de colectare limit (1–100) plus un opac cursor; nu analizați sau fabricați niciodată conținutul cursorului. POST, PATCH, și DELETE cererile cer Idempotency-Key; reîncercați aceeași operațiune cu aceeași cheie după expirarea timpului. Înregistrările de idepotență sunt păstrate timp de 7 zile. Răspunsurile includ X-Request-ID, sunt Cache-Control: no-store, iar toate erorile sunt JSON. Răspunsurile cu limita de rată sunt HTTP 429 cu Retry-After şi X-RateLimit-* antete. Câmpurile de corp/interogare necunoscute sunt respinse.

Contractul OpenAPI 3.1 care poate fi citit de mașină este distribuit ca resources/contracts/partner-api.openapi.yaml.

Creați o cheie API

Cerere

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

Complet key valoarea este returnată numai după creare sau rotație.

Listează cheile API

Cerere

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

Răspuns - 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"
    }
  ]
}

Lista este ordonată mai întâi cea mai nouă și folosește paginarea opac a cursorului. Pasa limit=1..100; când meta.has_more este adevărat, trimite meta.next_cursor ca urmatoarea cursor.

Obțineți o cheie API

Cerere

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

Răspuns - 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"
  }
}

Actualizați o cheie API

PATCH înlocuiește numai valorile mutabile acceptate. Pentru a elimina cheia dintr-un grup, trimiteți o cheie goală group_id. Pentru a moșteni setările de evaluare, trimiteți null pentru baza și multiplicatorul la nivel de cheie.

Cerere

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

Ștergeți o cheie API

Cerere

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ăspuns - 200

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

Înghețați și dezghețați o cheie

Cerere de înghețare

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

Răspunsul înghețat

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

Solicitare de dezghețare

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

Dezghețați răspunsul

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

Dezghețarea necesită un e-mail de proprietar verificat.

Rotiți o cheie

Cerere

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ăspuns - 200

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

Resetați utilizarea cheii

Cerere

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ăspuns - 200

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

Resetarea utilizării nu modifică cheltuielile pe durata vieții sau soldul contului.

Obțineți utilizarea cheii

Cerere

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

Răspuns - 200

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

Obțineți limita de cheltuieli și utilizarea rămasă

Cerere

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

Răspuns - 200

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

Când spend_limit este zero, este nelimitat și remaining este null.

Obțineți cele mai recente solicitări pentru o cheie

Istoricul detaliat al solicitărilor este un set de date de reținere la cald controlat de API_REQUESTS_HOT_RETENTION_DAYS (implicit 7 zile). Metadatele răspunsului raportează fereastra de păstrare activă. Utilizați tranzacțiile de sold pentru reconcilierea financiară pe termen lung.

limit este opțional, implicit este 10 și trebuie să fie un număr întreg de la 1 la 100. Solicitările finalizate sunt ordonate după finished_at cel mai nou primul. Când meta.has_more este true, trece meta.next_cursor ca opac before parametru de interogare pentru a prelua următoarea pagină mai veche. Nu analizați și nu construiți singur cursore.

Răspunsul conține rate de utilizator imuabile și rate oficiale per milion de token pentru cererile finalizate după migrare 059_request_pricing_audit_snapshot.sql. De asemenea, calculează pricing_snapshot.usage_price din ratele de bază salvate, multiplicatorul și istoricul fără a stoca un alt set de tarife. Acest lucru face ca evaluarea independentă a limitei de utilizare să fie auditată după modificarea prețurilor de catalog. Solicitările istorice create înainte de revenirea migrației 059 pricing_snapshot.available: false mai degrabă decât înlocuirea preţurilor curente. Solicitările executate prin API-uri batch compatibile cu Claude/OpenAI sunt marcate în mod explicit cu request_mode: "batch" și includeți protocolul lor, ID-ul sarcinii lot, custom_id, și multiplicatorul de preț al lotului instantaneu Model Gate.

Latența folosește nume stabile de afaceri/parteneri: gateway_overhead_ms, upstream_first_token_ms, și e2e_first_token_ms. Valoarea primului token E2E este măsurată de la începutul cererii Model Gate până la primul simbol de conținut real și exclude timpul de rețea/TLS de la partea clientului. Partner API expune doar explicit e2e_first_token_ms nume; coloana de stocare internă rămâne api_requests.first_token_ms.

Cerere

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

Răspuns - 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
  }
}

Pentru a continua cu următoarea pagină mai veche:

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 invalid before cursorul returnează HTTP 422. Cursorul conține doar poziția de la ora finală și ID-ul public al cererii externe; ID-urile de solicitare numerice interne nu sunt niciodată expuse.

Pentru solicitările asincrone sincrone și native, request_mode este sync sau async iar cel batch obiectul este omis. Instantaneul salvat cu rata de simboluri permite ca calculul de bază istoric să fie reprodus ca sum(tokens × snapshotted_rate / 1,000,000). Decontarea rotunjește suma de bază selectată la 10 zecimale și apoi calculează round(base_amount × multiplier, 10). Cele stocate cost, official_base_cost, și usage_cost câmpurile rămân cu autoritate.

Corpurile de cerere și răspuns brute nu sunt returnate niciodată de acest punct final.

Enumeră tranzacțiile de sold

Cerere

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

Răspuns - 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"
    }
  ]
}

Inferența facturabilă este reprezentată ca un rând de portofel pentru fiecare proprietar de facturare și pentru fiecare minut al orei de încheiere. transaction_id este identificatorul de registru public durabil. request_count este numărul de cereri incluse în acel minut de debit; billing_minute_num este floor(unix(finished_at)/60). Registrul intern brut id / source_id valorile nu sunt returnate. Rândurile agregate de utilizare API revin în mod intenționat null pentru balance_before, balance_after, și api_key_id; Detaliile exacte ale cheii/grupului/cererii rămân disponibile din istoricul cererilor și din minut de detalii ale panoului.

Obțineți soldul curent

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

Utilizați acest punct final după account.balance_low apeluri inverse pentru a reconcilia portofelul contului curent fără a necesita o autentificare Model API.

Listează evenimentele de audit ale partenerilor

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

Evenimentele de audit înregistrează mutații reușite ale managementului partenerilor cu ID-ul cererii, acțiunea, ținta, IP-ul sursă, starea, metadatele sigure și marcajul de timp UTC. Secretele, jetoanele purtător, textul simplu al cheii API, cheile de idempotizare, amprentele de solicitare și corpurile de reluare nu sunt stocate în metadatele de audit. Utilizare cursor pentru paginile următoare și opțional action filtrare.

Creați un grup

Cerere

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

Listează grupuri

Cerere

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

Răspuns

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

Obțineți sau actualizați un grup

Obțineți cerere

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

Obțineți răspuns

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

Solicitare de actualizare

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

Actualizați răspunsul

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

Ștergeți un grup

Un grup care nu este gol nu este șters. Mutați sau ștergeți mai întâi toate cheile API ale membrilor; în caz contrar, API-ul returnează HTTP 409 cu group_not_empty.

Cerere

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ăspuns

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

Cheile sunt detașate în funcție de comportamentul cheii externe ale bazei de date. Verificați calitatea de membru înainte de ștergere.

Resetați utilizarea grupului

Cerere

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ăspuns

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

Listează membrii grupului

Cerere

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

Răspuns

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

Adăugați o cheie la un grup

Cerere

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ăspuns

Răspunsul este lista actualizată de membri ai grupului:

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

Eliminați o cheie dintr-un grup

Cerere

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ăspuns

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

Obțineți utilizarea în grup

Cerere

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

Răspuns

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

Obțineți statistici de grup

from şi to acceptați numai marcajele de timp UTC RFC3339 care se termină în Z (sunt permise fracții de secunde până la 6 cifre). Statisticile sunt calculate numai din agregatele de cereri completate introduse de finished_at; minutul deschis curent este exclus în mod intenționat, astfel încât rezultatele pot întârzia până la cadența de agregare a minutelor.

average_duration_ms este durata medie completă a cererii Model Gate (duration_ms) în cererile finalizate în perioada selectată. Nu este latența primului token E2E, latența primului token în amonte sau supraîncărcarea gateway-ului. Partner API expune numai acest nume explicit al valorii.

Cerere

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ăspuns

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

Obțineți un rezultat asincron

Cerere

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

Procesarea răspunsului

{
  "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ăspuns completat

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

Erori comune

Cheie Partner API nevalidă — 401

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

Resursa nu a fost găsită - 404

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

Cerere nevalidă - 422

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

Mutarea nr. {0} de corpuri JSON este limitată la 1 MiB.

Conflict de neputință - 409

Aceeași Idempotency-Key a fost refolosit pentru o altă cerere. Generați o nouă cheie pentru o nouă operație logică.

Limita ratei - 429

Răspunsul conține error.code = partner_rate_limit_exceeded şi Retry-After. Reîncercați numai după întârzierea indicată.

Metoda nu este permisă - 405

Gazda partener returnează o eroare JSON plus HTTP Allow antet; nu se întoarce niciodată la o pagină de eroare HTML.

Regulile principale privind acreditările de afaceri

Pentru un simbol de companie Partner API, este acceptat numai proprietarul verificat al organizației. Cheile create prin Partner API folosesc acel proprietar atât ca proprietar de facturare, cât și ca principal al acreditării. Atribuirea angajat-principal se realizează în panoul web. group_id, atunci când este furnizat, trebuie să identifice un grup activ deținut de contul Business; valorile nevalide returnează HTTP 422 și nu reveniți niciodată la o cheie negrupată. Răspunsurile din istoricul cererilor pot include principal_user_id pentru a identifica principalul de acreditare independent de proprietatea facturării.