Partner API slutpunkter

Fyll i Partner API exempel på begäran och svar för nycklar, grupper, förfrågningar och transaktioner.

Partner API slutpunkter

Bas-URL:

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

Alla förfrågningar kräver:

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

Alla monetära värden och gränsvärden är JSON-decimalsträngar. Analysera dem inte som binära flyttal.

Gemensamma regler för bankintegration

Alla externa tidsstämplar är UTC RFC3339. Användning av samlingsslutpunkter limit (1–100) plus en ogenomskinlig cursor; analysera eller tillverka aldrig markörinnehåll. POST, PATCH, och DELETE förfrågningar kräver Idempotency-Key; Försök med samma åtgärd igen efter timeouts. Idempotensuppgifter bevaras i 7 dagar. Svaren inkluderar X-Request-ID, är Cache-Control: no-store, och alla fel är JSON. Frekvensgränssvar är HTTP 429 med Retry-After och X-RateLimit-* rubriker. Okända brödtext/frågefält avvisas.

Det maskinläsbara OpenAPI 3.1-kontraktet distribueras som resources/contracts/partner-api.openapi.yaml.

Skapa en API-nyckel

Begäran

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 kompletta key värde returneras först efter skapande eller rotation.

Lista API-nycklar

Begäran

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

Listan är beställd som den senaste först och använder ogenomskinlig markörpaginering. Passera limit=1..100; när meta.has_more är sant, skicka meta.next_cursor som nästa cursor.

Skaffa en API-nyckel

Begäran

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

Uppdatera en API-nyckel

PATCH ersätter endast de föränderliga värdena som stöds. För att ta bort nyckeln från en grupp, skicka en tom group_id. För att ärva värderingsinställningar, skicka null för nyckelnivåbasen och multiplikatorn.

Begäran

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

Ta bort en API-nyckel

Begäran

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 och frys upp en nyckel

Begäran 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 begäran

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

Unfreezing kräver en verifierad ägarens e-postadress.

Vrid på en nyckel

Begäran

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

Återställ nyckelanvändning

Begäran

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

Att återställa användningen ändrar inte livstidsutgifter eller kontosaldo.

Få nyckelanvändning

Begäran

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å utgiftsgräns och återstående användning

Begäran

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 är noll, det är obegränsat och remaining är null.

Få de senaste förfrågningarna om en nyckel

Detaljerad förfrågningshistorik är en datauppsättning för hot-retention som kontrolleras av API_REQUESTS_HOT_RETENTION_DAYS (standard 7 dagar). Svarsmetadata rapporterar det aktiva lagringsfönstret. Använd balanstransaktioner för långsiktig finansiell avstämning.

limit är valfritt, har som standard 10 och måste vara ett heltal från 1 till 100. Slutförda förfrågningar ordnas av finished_at nyaste först. När meta.has_more är true, passera meta.next_cursor som den ogenomskinliga before frågeparameter för att hämta nästa äldre sida. Analysera eller konstruera inte markörer själv.

Svaret innehåller oföränderliga priser för användare och officiella per miljon token för förfrågningar som slutförs efter migrering 059_request_pricing_audit_snapshot.sql. Den räknar också pricing_snapshot.usage_price från den sparade basen, multiplikatorn och historiska kurserna utan att lagra en annan kursuppsättning. Detta gör att den oberoende värderingen av användningsgränsen kan granskas efter katalogpriserna ändras. Historiska förfrågningar skapade före migrering 059 returnerar pricing_snapshot.available: false snarare än att ersätta nuvarande priser. Förfrågningar som körs via Claude/OpenAI-kompatibla batch-API:er är uttryckligen markerade med request_mode: "batch" och inkludera deras protokoll, batchjobb-ID, custom_id, och den ögonblicksbildade Model Gate batchprismultiplikatorn.

Latensen använder stabila företags-/partnernamn: gateway_overhead_ms, upstream_first_token_ms, och e2e_first_token_ms. E2E:s första token-värde mäts från Model Gate-begärans start till den första riktiga innehållstoken och exkluderar nätverks-/TLS-tid på klientsidan. Partner API exponerar endast det explicita e2e_first_token_ms namn; den interna lagringskolumnen finns kvar api_requests.first_token_ms.

Begäran

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

För att fortsätta med nästa äldre sida:

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 ogiltig before markören returnerar HTTP 422. Markören innehåller endast sluttidspositionen och extern begäran om offentligt ID; interna numeriska begärande-ID:n exponeras aldrig.

För synkrona och inbyggda asynkförfrågningar, request_mode är sync eller async och den batch objektet utelämnas. Den sparade token-rate ögonblicksbilden gör att den historiska basberäkningen kan reproduceras som sum(tokens × snapshotted_rate / 1,000,000). Avräkning avrundar det valda basbeloppet till 10 decimaler och räknar sedan ut round(base_amount × multiplier, 10). Den lagrade cost, official_base_cost, och usage_cost fälten förblir auktoritativa.

Obearbetade begäranden och svarsinstanser returneras aldrig av denna slutpunkt.

Lista saldotransaktioner

Begäran

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 slutledning representeras som en plånboksrad per faktureringsägare och sluttidsminut. transaction_id är den hållbara reskontraidentifieraren. request_count är antalet förfrågningar som ingår i den minutdebiteringen; billing_minute_num är floor(unix(finished_at)/60). Rå intern reskontra id / source_id värden returneras inte. Aggregerade API-användningsrader returneras avsiktligt null för balance_before, balance_after, och api_key_id; exakt information om nyckel/grupp/begäran förblir tillgänglig från förfrågningshistoriken och panelens minutdrill-down.

Få aktuell balans

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

Använd denna slutpunkt efter account.balance_low återuppringningar för att stämma av plånboken för nuvarande konto utan att kräva en modell API-referens.

Lista Partnerrevisionshändelser

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

Granskningshändelser registrerar framgångsrika partnerhanteringsmutationer med begäran-ID, åtgärd, mål, käll-IP, status, säker metadata och UTC-tidsstämpel. Hemligheter, bärartokens, klartext med API-nyckel, idempotensnycklar, begärande fingeravtryck och replay-kroppar lagras inte i granskningsmetadata. Använda cursor för efterföljande sidor och valfritt action filtrering.

Skapa en grupp

Begäran

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

Lista grupper

Begäran

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

Skaffa eller uppdatera en grupp

Få förfrågan

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

Uppdatera begäran

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

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

Ta bort en grupp

En icke-tom grupp tas inte bort. Flytta eller ta bort alla medlemmars API-nycklar först; annars returnerar API:et HTTP 409 med group_not_empty.

Begäran

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

Nycklar kopplas bort i enlighet med databasens främmande nyckelbeteende. Verifiera medlemskap innan radering.

Återställ gruppanvändning

Begäran

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

Lista gruppmedlemmar

Begäran

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

Lägg till en nyckel till en grupp

Begäran

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 är den uppdaterade gruppmedlemslistan:

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

Ta bort en nyckel från en grupp

Begäran

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å gruppanvändning

Begäran

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

from och to acceptera endast UTC RFC3339-tidsstämplar som slutar på Z (bråkdelar av sekunder upp till 6 siffror är tillåtna). Statistik beräknas endast från slutförda förfrågningsaggregat som knappats av finished_at; den för närvarande öppna minuten är avsiktligt utesluten, så resultaten kan släpa med upp till minutaggregeringskadensen.

average_duration_ms är den genomsnittliga fulla Model Gate-begäran varaktighet (duration_ms) över slutförda förfrågningar under den valda perioden. Det är inte E2E första token latens, uppströms första token latens eller gateway overhead. Partner API visar endast detta explicita mätvärdesnamn.

Begäran

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å ett asynkront resultat

Begäran

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

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

Färdigt 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"
  }
}

Vanliga fel

Ogiltig Partner API-nyckel – 401

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

Resursen hittades inte — 404

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

Ogiltig begäran — 422

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

Muterande Partner API JSON-kroppar är begränsade till 1 MiB.

Idempotenskonflikt — 409

Samma Idempotency-Key återanvändes för en annan begäran. Generera en ny nyckel för en ny logisk operation.

Prisgräns - 429

Svaret innehåller error.code = partner_rate_limit_exceeded och Retry-After. Försök igen först efter den angivna fördröjningen.

Metod inte tillåten — 405

Partnervärden returnerar ett JSON-fel plus HTTP Allow rubrik; det faller aldrig tillbaka till en HTML-felsida.

Huvudregler för affärsbehörighet

För en Business Partner API-token accepteras endast den verifierade organisationsägaren. Nycklar som skapats genom Partner API använder den ägaren som både faktureringsägare och användaruppgifter. Medarbetar-rektoruppdrag utförs i webbpanelen. group_id, när den tillhandahålls, måste identifiera en aktiv grupp som ägs av Business-kontot; ogiltiga värden returnerar HTTP 422 och fall aldrig tillbaka till en ogrupperad nyckel. Svar från förfrågningshistorik kan inkludera principal_user_id för att identifiera autentiseringsuppgifterna oberoende av faktureringsägande.