B2BB2B LLM

Partner API endepunkter

Fullfør Partner API eksempler på forespørsel og svar for nøkler, grupper, forespørsler og transaksjoner.

Partner API endepunkter

Grunnadresse:

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

Alle forespørsler krever:

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

Alle penge- og grenseverdier er JSON-desimalstrenger. Ikke analyser dem som binære flyttall.

Vanlige bankintegreringsregler

Alle eksterne tidsstempler er UTC RFC3339. Bruk av innsamlingsendepunkter limit (1–100) pluss en ugjennomsiktig cursor; aldri analyser eller produsere markørinnhold. POST, PATCH, og DELETE forespørsler krever Idempotency-Key; prøv den samme operasjonen på nytt med samme nøkkel etter timeouts. Idempotensjournaler oppbevares i 7 dager. Svarene inkluderer X-Request-ID, er Cache-Control: no-store, og alle feil er JSON. Frekvensgrensesvar er HTTP 429 med Retry-After og X-RateLimit-* overskrifter. Ukjent brødtekst/søkefelt er avvist.

Den maskinlesbare OpenAPI 3.1-kontrakten er distribuert som resources/contracts/partner-api.openapi.yaml.

Opprett en API-nøkkel

Forespørsel

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

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

Den komplette key verdi returneres bare etter opprettelse eller rotasjon.

List opp API-nøkler

Forespørsel

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

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

Listen er bestilt som nyeste først og bruker ugjennomsiktig markørpaginering. Pass limit=1..100; når meta.has_more er sant, send meta.next_cursor som den neste cursor.

Få én API-nøkkel

Forespørsel

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

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

Oppdater en API-nøkkel

PATCH erstatter bare de støttede mutable verdiene. For å fjerne nøkkelen fra en gruppe, send en tom group_id. For å arve verdivurderingsinnstillinger, send null for nøkkelnivåbasis og multiplikator.

Forespørsel

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

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

Slett en API-nøkkel

Forespørsel

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

Svar - 200

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

Frys og løs opp en nøkkel

Frysforespørsel

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

Frys respons

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

Opphev frysing av forespørsel

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

Frigjør svar

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

Unfreezing krever en bekreftet eier-e-postadresse.

Roter en nøkkel

Forespørsel

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

Svar - 200

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

Tilbakestill nøkkelbruk

Forespørsel

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

Svar - 200

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

Tilbakestilling av bruk endrer ikke levetidsforbruket eller kontosaldoen.

Få nøkkelbruk

Forespørsel

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

Svar - 200

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

Få forbruksgrense og gjenværende bruk

Forespørsel

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

Svar - 200

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

Når spend_limit er null, det er ubegrenset og remaining er null.

Få de siste forespørslene om en nøkkel

Detaljert forespørselshistorikk er et datasett for varmelagring kontrollert av API_REQUESTS_HOT_RETENTION_DAYS (standard 7 dager). Svarmetadataene rapporterer det aktive oppbevaringsvinduet. Bruk saldotransaksjoner for langsiktig økonomisk avstemming.

limit er valgfritt, har 10 som standard og må være et heltall fra 1 til 100. Ferdige forespørsler sorteres etter finished_at nyeste først. Når meta.has_more er true, bestå meta.next_cursor som den ugjennomsiktige before spørringsparameter for å hente neste eldre side. Ikke analyser eller konstruer markører selv.

Svaret inneholder uforanderlige bruker- og offisielle rater per million token for forespørsler fullført etter migrering 059_request_pricing_audit_snapshot.sql. Den beregner også pricing_snapshot.usage_price fra den lagrede basisen, multiplikatoren og historiske satsene uten å lagre et annet satssett. Dette gjør den uavhengige bruksgrenseverdien reviderbar etter at katalogprisene endres. Historiske forespørsler opprettet før migrering 059 returnerer pricing_snapshot.available: false i stedet for å erstatte gjeldende priser. Forespørsler utført gjennom Claude/OpenAI-kompatible batch-APIer er eksplisitt merket med request_mode: "batch" og inkludere deres protokoll, batch jobb-ID, custom_id, og den øyeblikksbildede Model Gate batchprismultiplikatoren.

Latency bruker stabile bedrifts-/partnernavn: gateway_overhead_ms, upstream_first_token_ms, og e2e_first_token_ms. E2E første-token-verdien måles fra Model Gate-forespørselsstart til det første virkelige innholdstokenet og ekskluderer nettverks-/TLS-tid på klientsiden. Partner API viser bare det eksplisitte e2e_first_token_ms navn; den interne lagringskolonnen forblir api_requests.first_token_ms.

Forespørsel

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

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

For å fortsette med neste eldre side:

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

En ugyldig before markøren returnerer HTTP 422. Markøren inneholder bare slutttidsposisjonen og den eksterne forespørselens offentlige ID; interne numeriske forespørsels-IDer blir aldri eksponert.

For synkrone og native async-forespørsler, request_mode er sync eller async og den batch objekt er utelatt. Det lagrede øyeblikksbildet av token-rate lar den historiske basisberegningen reproduseres som sum(tokens × snapshotted_rate / 1,000,000). Oppgjør runder det valgte grunnbeløpet til 10 desimaler og beregner deretter round(base_amount × multiplier, 10). Den lagrede cost, official_base_cost, og usage_cost felt forblir autoritative.

Rå forespørsels- og svarinstanser returneres aldri av dette endepunktet.

List opp saldotransaksjoner

Forespørsel

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

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

Fakturerbar slutning er representert som én lommebok-rad per faktureringseier og slutttidsminutt. transaction_id er den varige identifikatoren for offentlig hovedbok. request_count er antallet forespørsler som er inkludert i den minuttbelastningen; billing_minute_num er floor(unix(finished_at)/60). Rå intern hovedbok id / source_id verdier returneres ikke. Samlede API-bruksrader returnerer med hensikt null til balance_before, balance_after, og api_key_id; nøyaktig nøkkel/gruppe/forespørselsdetaljer forblir tilgjengelig fra forespørselshistorikken og panelminuttdrill-down.

Få gjeldende saldo

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

Bruk dette endepunktet etter account.balance_low tilbakeringinger for å avstemme gjeldende kontolommebok uten å kreve en Model API-legitimasjon.

List opp partnerrevisjonshendelser

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

Revisjonshendelser registrerer vellykkede partneradministrasjonsmutasjoner med forespørsels-ID, handling, mål, kilde-IP, status, sikre metadata og UTC-tidsstempel. Hemmeligheter, bærersymboler, klartekst med API-nøkler, idempotensnøkler, forespørselsfingeravtrykk og gjenopptagelseskropper lagres ikke i revisjonsmetadata. Bruk cursor for påfølgende sider og valgfritt action filtrering.

Opprett en gruppe

Forespørsel

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

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

List grupper

Forespørsel

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

Svar

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

Få eller oppdater en gruppe

Få forespørsel

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

Få svar

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

Oppdateringsforespørsel

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

Oppdater svar

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

Slett en gruppe

En ikke-tom gruppe slettes ikke. Flytt eller slett alle medlems-API-nøkler først; ellers returnerer APIen HTTP 409 med group_not_empty.

Forespørsel

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

Svar

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

Keys are detached according to the database foreign-key behavior. Bekreft medlemskap før sletting.

Tilbakestill gruppebruk

Forespørsel

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

Svar

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

List gruppemedlemmer

Forespørsel

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

Svar

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

Legg til en nøkkel til en gruppe

Forespørsel

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

Svar

Svaret er den oppdaterte gruppemedlemslisten:

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

Fjern en nøkkel fra en gruppe

Forespørsel

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

Svar

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

Få gruppebruk

Forespørsel

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

Svar

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

Få gruppestatistikk

from og to godta bare UTC RFC3339-tidsstempler som slutter på Z (brøkdeler av sekunder opptil 6 sifre er tillatt). Statistikk beregnes bare fra fullførte forespørselsaggregater tastet inn av finished_at; det for øyeblikket åpne minuttet er med vilje ekskludert, så resultatene kan forsinke med opptil minuttaggregeringskadensen.

average_duration_ms er gjennomsnittlig full Model Gate-forespørselsvarighet (duration_ms) på tvers av fullførte forespørsler i den valgte perioden. Det er ikke E2E første-token-latens, oppstrøms første-token-latens eller gateway-overhead. Partner API viser bare dette eksplisitte metriske navnet.

Forespørsel

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

Svar

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

Få et asynkront resultat

Forespørsel

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

Behandler svar

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

Fullført svar

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

Vanlige feil

Ugyldig Partner API-nøkkel – 401

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

Ressursen ikke funnet - 404

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

Ugyldig forespørsel – 422

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

Muterende Partner API JSON-kropper er begrenset til 1 MiB.

Idempotenskonflikt - 409

Det samme Idempotency-Key ble gjenbrukt for en annen forespørsel. Generer en ny nøkkel for en ny logisk operasjon.

Satsgrense - 429

Svaret inneholder error.code = partner_rate_limit_exceeded og Retry-After. Prøv igjen bare etter den angitte forsinkelsen.

Metode ikke tillatt - 405

Partnerverten returnerer en JSON-feil pluss HTTP Allow header; den faller aldri tilbake til en HTML-feilside.

Hovedregler for forretningslegitimasjon

For et Business Partner API-token er det bare den bekreftede organisasjonseieren som godtas. Nøkler opprettet gjennom Partner API bruker denne eieren som både faktureringseier og legitimasjonsoppdragsgiver. Ansatt-rektoroppdrag utføres i webpanelet. group_id, når den leveres, må identifisere en aktiv gruppe som eies av Business-kontoen; ugyldige verdier returnerer HTTP 422 og fall aldri tilbake til en ugruppert nøkkel. Forespørselshistorikksvar kan inkludere principal_user_id for å identifisere legitimasjonsprinsippet uavhengig av eierskap for fakturering.