B2BB2B LLM

Partner API koncových bodů

Dokončete Partner API příklady požadavků a odpovědí pro klíče, skupiny, požadavky a transakce.

Partner API koncových bodů

Základní URL:

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

Všechny žádosti vyžadují:

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

Všechny peněžní a limitní hodnoty jsou JSON desítkové řetězce. Neanalyzujte je jako binární čísla s plovoucí desetinnou čárkou.

Společná pravidla integrace bank

Všechna externí časová razítka jsou UTC RFC3339. Použití koncových bodů sběru limit (1–100) plus neprůhledné cursor; nikdy neanalyzujte ani nevytvářejte obsah kurzoru. POST, PATCHa DELETE žádosti vyžadují Idempotency-Key; opakujte stejnou operaci se stejným klíčem po uplynutí časových limitů. Záznamy o idempotenci jsou uchovávány po dobu 7 dnů. Odpovědi zahrnují X-Request-ID, jsou Cache-Control: no-storea všechny chyby jsou JSON. Odpovědi s limitem rychlosti jsou HTTP 429 s Retry-After a X-RateLimit-* hlavičky. Neznámá pole těla/dotazu jsou odmítnuta.

Strojově čitelná smlouva OpenAPI 3.1 je distribuována jako resources/contracts/partner-api.openapi.yaml.

Vytvořte klíč API

Žádost

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

Odpověď - 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"
  }
}

Kompletní key hodnota je vrácena pouze po vytvoření nebo otočení.

Seznam klíčů API

Žádost

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

Odpověď - 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"
    }
  ]
}

Seznam je řazen od nejnovějšího a používá neprůhledné kurzorové stránkování. Přihrávka limit=1..100; když meta.has_more je pravda, pošli meta.next_cursor jako další cursor.

Získejte jeden klíč API

Žádost

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

Odpověď - 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"
  }
}

Aktualizujte klíč API

PATCH nahradí pouze podporované měnitelné hodnoty. Chcete-li odebrat klíč ze skupiny, odešlete prázdný group_id. Chcete-li zdědit nastavení ocenění, odešlete null pro základ na úrovni klíče a multiplikátor.

Žádost

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

Odpověď - 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"
  }
}

Odstraňte klíč API

Žádost

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

Odpověď - 200

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

Zmrazit a rozmrazit klíč

Žádost o zmrazení

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

Zmrazit odezvu

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

Rozmrazit požadavek

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

Zrušit zmrazení odpovědi

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

Rozmrazení vyžaduje e-mail ověřeného vlastníka.

Otočte klíčem

Žádost

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

Odpověď - 200

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

Resetovat použití klíče

Žádost

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

Odpověď - 200

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

Resetováním používání se nezmění celkové výdaje ani zůstatek účtu.

Získejte využití klíče

Žádost

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

Odpověď - 200

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

Získejte limit útraty a zbývající využití

Žádost

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

Odpověď - 200

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

Když spend_limit je nula, je neomezená a remaining je null.

Získejte nejnovější požadavky na klíč

Podrobná historie požadavků je datová sada pro uchovávání za provozu, kterou řídí API_REQUESTS_HOT_RETENTION_DAYS (výchozí 7 dní). Metadata odpovědi hlásí okno aktivního uchování. Použijte bilanční transakce pro dlouhodobější finanční odsouhlasení.

limit je volitelný, výchozí je 10 a musí být celé číslo od 1 do 100. Dokončené požadavky jsou seřazeny podle finished_at nejnovější jako první. Když meta.has_more je true, projít meta.next_cursor jako neprůhledné before parametr dotazu pro načtení další starší stránky. Neanalyzujte ani nevytvářejte kurzory sami.

Odpověď obsahuje neměnné uživatelské a oficiální sazby za milion tokenů pro požadavky dokončené po migraci 059_request_pricing_audit_snapshot.sql. Také počítá pricing_snapshot.usage_price z uloženého základu, multiplikátoru a historických sazeb bez uložení další sady sazeb. Díky tomu je nezávislé ocenění limitu použití auditovatelné po změně katalogových cen. Historické požadavky vytvořené před migrací 059 se vrátí pricing_snapshot.available: false místo nahrazování současných cen. Požadavky prováděné prostřednictvím dávkových rozhraní API kompatibilních s Claude/OpenAI jsou výslovně označeny request_mode: "batch" a zahrnout jejich protokol, ID dávkové úlohy, custom_ida nasnímaný multiplikátor ceny šarže Model Gate.

Latence používá stabilní názvy firem/partnerů: gateway_overhead_ms, upstream_first_token_msa e2e_first_token_ms. Hodnota prvního tokenu E2E se měří od začátku požadavku Model Gate po první token skutečného obsahu a nezahrnuje čas sítě/TLS na straně klienta. Partner API odhaluje pouze explicitní e2e_first_token_ms jméno; sloupek vnitřního úložiště zůstává api_requests.first_token_ms.

Žádost

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

Odpověď - 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
  }
}

Chcete-li pokračovat na další starší stránce:

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

Neplatný before kurzor vrací HTTP 422. Kurzor obsahuje pouze koncovou pozici a veřejné ID externího požadavku; interní číselná ID požadavků nejsou nikdy odhalena.

Pro synchronní a nativní asynchronní požadavky, request_mode je sync nebo async a batch objekt je vynechán. Uložený snímek rychlosti tokenu umožňuje reprodukovat historický základní výpočet jako sum(tokens × snapshotted_rate / 1,000,000). Vypořádání zaokrouhlí vybranou základní částku na 10 desetinných míst a poté vypočítá round(base_amount × multiplier, 10). Uložené cost, official_base_costa usage_cost pole zůstávají směrodatná.

Tento koncový bod nikdy nevrací nezpracovaná těla požadavků a odpovědí.

Seznam zůstatkových transakcí

Žádost

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

Odpověď - 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"
    }
  ]
}

Fakturovatelné odvození je reprezentováno jako jeden řádek peněženky na vlastníka fakturace a minutu doby dokončení. transaction_id je trvalý identifikátor veřejné knihy. request_count je počet požadavků zahrnutých v tomto minutovém debetu; billing_minute_num je floor(unix(finished_at)/60). Nezpracovaná vnitřní účetní kniha id / source_id hodnoty nejsou vráceny. Řádky agregovaného využití API se záměrně vracejí null pro balance_before, balance_aftera api_key_id; přesný klíč/skupina/podrobnosti požadavku zůstávají k dispozici z historie požadavků a minutového rozbalení panelu.

Získejte aktuální zůstatek

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

Použijte tento koncový bod po account.balance_low zpětná volání pro sladění peněženky aktuálního účtu bez vyžadování pověření Model API.

Seznam událostí auditu partnera

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

Události auditu zaznamenávají úspěšné mutace správy partnera s ID požadavku, akcí, cílem, zdrojovou IP, stavem, bezpečnými metadaty a časovým razítkem UTC. Tajemství, tokeny nosiče, prostý text klíče API, klíče idempotence, otisky prstů požadavků a těla přehrávání nejsou uloženy v metadatech auditu. Použití cursor pro další stránky a volitelné action filtrování.

Vytvořte skupinu

Žádost

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

Odpověď - 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"
  }
}

Seznam skupin

Žádost

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

Odpověď

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

Získejte nebo aktualizujte skupinu

Získejte žádost

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

Získejte odpověď

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

Žádost o aktualizaci

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

Aktualizovat odpověď

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

Smazat skupinu

Neprázdná skupina nebude odstraněna. Nejprve přesuňte nebo odstraňte všechny klíče API členů; jinak API vrátí HTTP 409 s group_not_empty.

Žádost

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

Odpověď

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

Klíče jsou odpojeny podle chování cizího klíče databáze. Před smazáním ověřte členství.

Resetovat použití skupiny

Žádost

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

Odpověď

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

Seznam členů skupiny

Žádost

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

Odpověď

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

Přidejte klíč do skupiny

Žádost

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

Odpověď

Odpovědí je aktualizovaný seznam členů skupiny:

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

Odebrat klíč ze skupiny

Žádost

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

Odpověď

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

Získejte skupinové využití

Žádost

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

Odpověď

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

Získejte skupinové statistiky

from a to přijímat pouze časová razítka UTC RFC3339 končící na Z (jsou povoleny zlomky sekund až 6 číslic). Statistiky se počítají pouze z agregací dokončených požadavků zadaných pomocí finished_at; aktuálně otevřená minuta je záměrně vyloučena, takže výsledky mohou zaostávat až o minutovou agregační kadenci.

average_duration_ms je průměrné úplné trvání požadavku Model Gate (duration_ms) napříč dokončenými požadavky ve zvoleném období. Nejedná se o latenci prvního tokenu E2E, latenci prvního tokenu upstream nebo režii brány. Partner API odhaluje pouze tento explicitní název metriky.

Žádost

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

Odpověď

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

Získejte asynchronní výsledek

Žádost

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

Zpracování odezvy

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

Dokončená odpověď

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

Běžné chyby

Neplatný klíč Partner API – 401

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

Zdroj nenalezen — 404

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

Neplatný požadavek — 422

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

Mutující těla JSON Partner API jsou omezena na 1 MiB.

Konflikt idempotence — 409

To samé Idempotency-Key byl znovu použit pro jiný požadavek. Vygenerujte nový klíč pro novou logickou operaci.

Limit sazby – 429

Odpověď obsahuje error.code = partner_rate_limit_exceeded a Retry-After. Zkuste to znovu až po uvedené prodlevě.

Metoda není povolena – 405

Partnerský hostitel vrátí chybu JSON plus HTTP Allow hlavička; nikdy se nevrátí na chybovou stránku HTML.

Základní pravidla obchodního pověření

U tokenu firmy Partner API je přijímán pouze ověřený vlastník organizace. Klíče vytvořené prostřednictvím Partner API používají tohoto vlastníka jako vlastníka fakturace i pověření. Zadání zaměstnanec-ředitel se provádí ve webovém panelu. group_id, je-li dodán, musí identifikovat aktivní skupinu vlastněnou obchodním účtem; neplatné hodnoty vrátí HTTP 422 a nikdy se nevracejte k neseskupenému klíči. Odpovědi historie požadavků mohou zahrnovat principal_user_id k identifikaci pověření nezávisle na vlastnictví fakturace.