B2BB2B LLM

Partner API slutpunkter

Udfyld Partner API anmodnings- og svareksempler for nøgler, grupper, anmodninger og transaktioner.

Partner API slutpunkter

Basis URL:

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

Alle anmodninger kræver:

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

Alle penge- og grænseværdier er JSON-decimalstrenge. Undlad at analysere dem som binære flydende kommatal.

Fælles bankintegrationsregler

Alle eksterne tidsstempler er UTC RFC3339. Brug af indsamlingsendepunkter limit (1-100) plus en uigennemsigtig cursor; parse eller fremstille aldrig markørindhold. POST, PATCH, og DELETE anmodninger kræver Idempotency-Key; prøv den samme handling igen med den samme tast efter timeouts. Idempotensjournaler opbevares i 7 dage. Svar inkluderer X-Request-ID, er Cache-Control: no-store, og alle fejl er JSON. Rate-limit svar er HTTP 429 med Retry-After og X-RateLimit-* overskrifter. Ukendte brødtekst/forespørgselsfelter afvises.

Den maskinlæsbare OpenAPI 3.1-kontrakt distribueres som resources/contracts/partner-api.openapi.yaml.

Opret en API-nøgle

Anmodning

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 værdi returneres først efter oprettelse eller rotation.

Liste over API-nøgler

Anmodning

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 bruger uigennemsigtig markørpaginering. Passere limit=1..100; når meta.has_more er sandt, send meta.next_cursor som den næste cursor.

Få én API-nøgle

Anmodning

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

Opdater en API-nøgle

PATCH erstatter kun de understøttede mutable værdier. For at fjerne nøglen fra en gruppe, send en tom group_id. Send for at arve værdiansættelsesindstillinger null for nøgleniveau-basis og multiplikator.

Anmodning

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

Slet en API-nøgle

Anmodning

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 frigør en nøgle

Anmodning om frysning

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 svar

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

Frigør anmodning

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

Frigør svar

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

Frigørelse kræver en bekræftet ejer-e-mail.

Drej en nøgle

Anmodning

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

Nulstil nøglebrug

Anmodning

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

Nulstilling af brug ændrer ikke levetidsforbrug eller kontosaldo.

Få nøglebrug

Anmodning

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å forbrugsgrænse og resterende forbrug

Anmodning

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 nul, det er ubegrænset og remaining er null.

Få de seneste anmodninger om en nøgle

Detaljeret anmodningshistorik er et hot-retention datasæt styret af API_REQUESTS_HOT_RETENTION_DAYS (standard 7 dage). Svarmetadataene rapporterer det aktive opbevaringsvindue. Brug saldotransaktioner til langsigtet økonomisk afstemning.

limit er valgfri, er som standard 10 og skal være et heltal fra 1 til 100. Afsluttede anmodninger er sorteret efter finished_at nyeste først. Når meta.has_more er true, bestå meta.next_cursor som den uigennemsigtige before forespørgselsparameter for at hente den næste ældre side. Undlad at analysere eller konstruere markører selv.

Svaret indeholder uforanderlige bruger- og officielle rater pr. million token for anmodninger, der er gennemført efter migrering 059_request_pricing_audit_snapshot.sql. Den beregner også pricing_snapshot.usage_price fra den gemte basis, multiplikator og historiske satser uden at gemme et andet satssæt. Dette gør den uafhængige værdiansættelse af brugsgrænsen revideret, efter at katalogpriserne ændres. Historiske anmodninger oprettet før migrering 059 returnerer pricing_snapshot.available: false i stedet for at erstatte de nuværende priser. Anmodninger udført gennem Claude/OpenAI-kompatible batch-API'er er eksplicit markeret med request_mode: "batch" og inkludere deres protokol, batchjob-id, custom_id, og den øjebliksbillede af Model Gate-batchprismultiplikatoren.

Latency bruger stabile virksomheds-/partnernavne: gateway_overhead_ms, upstream_first_token_ms, og e2e_first_token_ms. E2E first-token-værdien måles fra Model Gate-anmodningsstart til det første rigtige indholdstoken og ekskluderer netværks-/TLS-tid på klientsiden. Partner API afslører kun det eksplicitte e2e_first_token_ms navn; den interne lagersøjle forbliver api_requests.first_token_ms.

Anmodning

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

Sådan fortsætter du med den næste ældre 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 indeholder kun sluttidspositionen og den eksterne anmodnings offentlige ID; interne numeriske anmodnings-id'er afsløres aldrig.

For synkrone og native async-anmodninger, request_mode er sync eller async og den batch objekt er udeladt. Det gemte token-rate snapshot gør det muligt at reproducere den historiske basisberegning som sum(tokens × snapshotted_rate / 1,000,000). Afregning afrunder det valgte grundbeløb til 10 decimaler og beregner derefter round(base_amount × multiplier, 10). Den opbevarede cost, official_base_cost, og usage_cost felter forbliver autoritative.

Rå anmodnings- og svarinstanser returneres aldrig af dette slutpunkt.

Liste saldotransaktioner

Anmodning

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 repræsenteret som én tegnebogsrække pr. faktureringsejer og sluttidsminut. transaction_id er den holdbare offentlige finans-id. request_count er antallet af anmodninger inkluderet i den pågældende minutdebitering; billing_minute_num er floor(unix(finished_at)/60). Rå intern hovedbog id / source_id værdier returneres ikke. Aggregerede API-brugsrækker vender bevidst tilbage null for balance_before, balance_after, og api_key_id; nøjagtige nøgle/gruppe/anmodningsdetaljer forbliver tilgængelige fra anmodningshistorikken og panelets minut-drill-down.

Få den aktuelle 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"}}

Brug dette endepunkt efter account.balance_low tilbagekald for at afstemme den aktuelle kontos tegnebog uden at kræve et Model API-legitimationsoplysninger.

Liste over partnerrevisionsbegivenheder

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

Revisionsbegivenheder registrerer vellykkede partneradministrationsmutationer med anmodnings-id, handling, mål, kilde-IP, status, sikre metadata og UTC-tidsstempel. Hemmeligheder, bærer-tokens, API-nøgle klartekst, idempotensnøgler, anmodningsfingeraftryk og genafspilningslegemer gemmes ikke i revisionsmetadata. Bruge cursor for efterfølgende sider og valgfrit action filtrering.

Opret en gruppe

Anmodning

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

Liste grupper

Anmodning

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 opdater en gruppe

Få anmodning

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

Opdateringsanmodning

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

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

Slet en gruppe

En ikke-tom gruppe slettes ikke. Flyt eller slet alle medlems-API-nøgler først; ellers returnerer API'en HTTP 409 med group_not_empty.

Anmodning

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

Nøgler adskilles i henhold til databasens fremmednøgleadfærd. Bekræft medlemskab før sletning.

Nulstil gruppebrug

Anmodning

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

Liste gruppemedlemmer

Anmodning

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

Tilføj en nøgle til en gruppe

Anmodning

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 opdaterede gruppemedlemsliste:

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

Fjern en nøgle fra en gruppe

Anmodning

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å gruppebrug

Anmodning

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å gruppestatistik

from og to accepter kun UTC RFC3339-tidsstempler, der ender på Z (brøkdele af sekunder op til 6 cifre er tilladt). Statistikker beregnes kun ud fra aggregater med fuldførte anmodninger indtastet af finished_at; det aktuelt åbne minut er bevidst udelukket, så resultaterne kan forsinke med op til minutsammenlægningskadencen.

average_duration_ms er den gennemsnitlige fulde Model Gate-anmodningsvarighed (duration_ms) på tværs af afsluttede anmodninger i den valgte periode. Det er ikke E2E first-token latency, upstream first token latency eller gateway overhead. Partner API viser kun dette eksplicitte metriske navn.

Anmodning

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

Anmodning

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

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

Almindelige fejl

Ugyldig Partner API-nøgle – 401

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

Ressource ikke fundet - 404

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

Ugyldig anmodning — 422

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

Muterende Partner API JSON-kroppe er begrænset til 1 MiB.

Idempotenskonflikt — 409

Det samme Idempotency-Key blev genbrugt til en anden anmodning. Generer en ny nøgle til en ny logisk operation.

Satsgrænse - 429

Svaret indeholder error.code = partner_rate_limit_exceeded og Retry-After. Prøv først igen efter den angivne forsinkelse.

Metode ikke tilladt - 405

Partnerværten returnerer en JSON-fejl plus HTTP Allow overskrift; det falder aldrig tilbage til en HTML-fejlside.

Hovedregler for forretningslegitimation

For et Business Partner API-token accepteres kun den bekræftede organisationsejer. Nøgler oprettet gennem Partner API bruger denne ejer som både faktureringsejer og legitimationsansvarlig. Medarbejder-rektor opgave udføres i webpanelet. group_id, når den leveres, skal identificere en aktiv gruppe, der ejes af Business-kontoen; ugyldige værdier returnerer HTTP 422 og fald aldrig tilbage til en ugrupperet nøgle. Anmodningshistoriksvar kan omfatte principal_user_id at identificere legitimationsoplysningerne uafhængigt af faktureringsejerskab.