Partner API végpont
Töltse ki a Partner API. számú kérés- és válaszpéldákat kulcsokhoz, csoportokhoz, kérésekhez és tranzakciókhoz.
Partner API végpont
Alap URL:
https://p-api.model-gate.comMinden kérés megköveteli:
Authorization: Bearer mg_partner_...
Accept: application/jsonMinden pénzbeli és határérték JSON decimális karakterlánc. Ne elemezze őket bináris lebegőpontos számként.
Közös banki integrációs szabályok
Minden külső időbélyeg UTC RFC3339. Gyűjtemény végpontok használata limit (1–100) plusz egy átlátszatlan cursor; soha ne elemezze vagy készítse el a kurzor tartalmát. POST, PATCH, és DELETE kérések megkövetelik Idempotency-Key; ismételje meg ugyanazt a műveletet ugyanazzal a kulccsal az időtúllépések után. Az identitásrekordokat 7 napig őrzik meg. A válaszok közé tartozik X-Request-ID, vannak Cache-Control: no-store, és minden hiba JSON. A sebességkorlát válaszok HTTP 429 -vel Retry-After és X-RateLimit-* fejlécek. Az ismeretlen törzs/lekérdezés mezők elutasítva.
A géppel olvasható OpenAPI 3.1 szerződést a következő néven terjesztik resources/contracts/partner-api.openapi.yaml.
Hozzon létre egy API-kulcsot
Kér
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"
}'Válasz – 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"
}
}A teljes key érték csak létrehozás vagy forgatás után kerül visszaadásra.
Az API kulcsok listája
Kér
curl https://p-api.model-gate.com/api/v1/partner/keys \
-H "Authorization: Bearer mg_partner_..."Válasz: 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"
}
]
}A lista a legfrissebb sorrendben kezdődik, és átlátszatlan kurzoroldalszámozást használ. Pass limit=1..100; amikor meta.has_more igaz, küldje el meta.next_cursor mint a következő cursor.
Szerezzen be egy API-kulcsot
Kér
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."Válasz: 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"
}
}Frissítsen egy API-kulcsot
PATCH csak a támogatott változtatható értékeket helyettesíti. A kulcs csoportból való eltávolításához küldjön egy üres üzenetet group_id. Az értékelési beállítások örökléséhez küldje el null kulcsszintű alaphoz és szorzóhoz.
Kér
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
}'Válasz: 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"
}
}API-kulcs törlése
Kér
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" \Válasz: 200
{"data":{"deleted":true}}Kulcs lefagyasztása és feloldása
Lefagyasztási kérelem
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" \Válasz lefagyása
{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}Feloldási kérés
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" \A válasz feloldása
{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}A lefagyás feloldásához igazolt tulajdonosi e-mail-cím szükséges.
Forgassa el a kulcsot
Kér
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" \Válasz: 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"status": "active",
"key_prefix": "mg_live_cd34",
"key": "mg_live_cd34..."
}
}Kulcshasználat visszaállítása
Kér
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" \Válasz: 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"usage": "0.0000000000",
"total_spent": "1.1400000000"
}
}A használat alaphelyzetbe állítása nem változtatja meg az élettartamra szóló ráfordítást vagy a számlaegyenleget.
Kulcshasználat megszerzése
Kér
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."Válasz: 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"usage": "3.2500000000",
"total_spent": "1.1400000000"
}
}Költési korlát és fennmaradó használat
Kér
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
-H "Authorization: Bearer mg_partner_..."Válasz: 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"spend_limit": "20.0000000000",
"usage": "3.2500000000",
"remaining": "16.7500000000"
}
}Amikor spend_limit nulla, korlátlan és remaining van null.
Szerezze meg a legújabb kulcskéréseket
A részletes kérelmek előzményei egy folyamatos megőrzésű adatkészlet, amelyet a API_REQUESTS_HOT_RETENTION_DAYS (alapértelmezett 7 nap). A válasz metaadatai az aktív megőrzési ablakot jelentik. Hosszabb távú pénzügyi egyeztetéshez használjon egyenleg-tranzakciókat.
limit opcionális, alapértelmezés szerint 10, és 1 és 100 közötti egész számnak kell lennie. A véglegesített kérelmek sorrendje finished_at a legújabb az első. Amikor meta.has_more van true, passz meta.next_cursor mint az átlátszatlan before lekérdezési paramétert a következő régebbi oldal lekéréséhez. Ne elemezze vagy konstruálja a kurzorokat saját maga.
A válasz megváltoztathatatlan felhasználói és hivatalos milliós token-arányokat tartalmaz az áttelepítés után befejezett kérésekre vonatkozóan 059_request_pricing_audit_snapshot.sql. Számít is pricing_snapshot.usage_price a mentett alapból, szorzóból és korábbi árfolyamokból anélkül, hogy másik árfolyamkészletet tárolna. Ezáltal a független használati határérték-értékelés a katalógusárak változása után auditálhatóvá válik. A 059-es áttelepítés előtt létrehozott korábbi kérések visszatérnek pricing_snapshot.available: false a jelenlegi árak helyett. A Claude/OpenAI-kompatibilis kötegelt API-kon keresztül végrehajtott kérések kifejezetten meg vannak jelölve request_mode: "batch" és tartalmazza a protokolljukat, a kötegelt feladat azonosítóját, custom_id, és a pillanatfelvételen készült Model Gate kötegár szorzó.
A késleltetés stabil üzleti/partnerneveket használ: gateway_overhead_ms, upstream_first_token_ms, és e2e_first_token_ms. Az E2E első token értékét a modellkapu-kérés kezdetétől az első valódi tartalomjogkivonatig mérjük, és nem tartalmazza az ügyféloldali hálózati/TLS-időt. A Partner API csak az expliciteket fedi fel e2e_first_token_ms név; a belső tárolóoszlop megmarad api_requests.first_token_ms.
Kér
curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
-H "Authorization: Bearer mg_partner_..."Válasz: 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
}
}A következő régebbi oldal folytatásához:
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_..."Egy érvénytelen before a kurzor a HTTP-t adja vissza 422. A kurzor csak a befejezési időpont pozícióját és a külső kérés nyilvános azonosítóját tartalmazza; A belső numerikus kérésazonosítók soha nem kerülnek nyilvánosságra.
Szinkron és natív aszinkron kérések esetén request_mode van sync vagy async és a batch objektum kimaradt. A mentett token-arányos pillanatkép lehetővé teszi az előzményalap-számítás formátumban történő reprodukálását sum(tokens × snapshotted_rate / 1,000,000). Az elszámolás a kiválasztott alapösszeget 10 tizedesjegyre kerekíti, majd kiszámítja round(base_amount × multiplier, 10). A tárolt cost, official_base_cost, és usage_cost mezők továbbra is mérvadóak.
Ez a végpont soha nem küldi vissza a nyers kérés- és választesteket.
Egyenlegtranzakciók listázása
Kér
curl https://p-api.model-gate.com/api/v1/partner/transactions \
-H "Authorization: Bearer mg_partner_..."Válasz: 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"
}
]
}A számlázható következtetés egy pénztárca-főkönyvi sorként jelenik meg számlázási tulajdonosonként és befejezési idő percenként. transaction_id a tartós nyilvános főkönyvi azonosító. request_count az adott perc terhelésben szereplő kérelmek száma; billing_minute_num van floor(unix(finished_at)/60). Nyers belső főkönyv id / source_id értékeket nem adnak vissza. Az összesített API-használati sorok szándékosan térnek vissza null számára balance_before, balance_after, és api_key_id; A pontos kulcs/csoport/kérés részletei elérhetők maradnak a kéréselőzményekből és a panel percenkénti lebontásából.
Szerezze meg az aktuális egyenleget
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"}}Ezt a végpontot használja ezután account.balance_low visszahívások az aktuális fiók pénztárca összeegyeztetéséhez Model API hitelesítő adatok nélkül.
Partner auditálási események listázása
curl "https://p-api.model-gate.com/api/v1/partner/audit-events?limit=100" \
-H "Authorization: Bearer mg_partner_..."Az audit események rögzítik a sikeres partnerkezelési mutációkat kérésazonosítóval, művelettel, céllal, forrás IP-címmel, állapottal, biztonságos metaadatokkal és UTC időbélyeggel. A titkokat, a vivőjogkivonatokat, az API-kulcs egyszerű szövegét, az idempotenciakulcsokat, a kérés ujjlenyomatait és a visszajátszási törzseket nem tárolják az ellenőrzési metaadatok. Használat cursor a következő oldalakhoz és opcionális action szűrő.
Hozzon létre egy csoportot
Kér
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"
}'Válasz – 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"
}
}Csoportok listázása
Kér
curl https://p-api.model-gate.com/api/v1/partner/groups \
-H "Authorization: Bearer mg_partner_..."Válasz
{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}Csoport létrehozása vagy frissítése
Kérjen kérést
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."Választ kapni
{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}Frissítési kérés
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"}'Válasz frissítése
{"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"}}Csoport törlése
A nem üres csoport nem törlődik. Először helyezze át vagy törölje az összes tag API-kulcsot; ellenkező esetben az API HTTP-t ad vissza 409 -vel group_not_empty.
Kér
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" \Válasz
{"data":{"deleted":true}}A kulcsok leválasztása az adatbázis idegen kulcs viselkedésének megfelelően történik. A törlés előtt igazolja a tagságot.
Csoporthasználat visszaállítása
Kér
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" \Válasz
{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}Csoporttagok listázása
Kér
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
-H "Authorization: Bearer mg_partner_..."Válasz
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}Kulcs hozzáadása egy csoporthoz
Kér
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"}'Válasz
A válasz a frissített csoporttaglista:
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active"}]}Kulcs eltávolítása egy csoportból
Kér
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" \Válasz
{"data":{"removed":true}}Csoportos használat
Kér
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."Válasz
{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}Csoportstatisztikák lekérése
from és to csak a számokra végződő UTC RFC3339 időbélyegeket fogadja el Z (legfeljebb 6 számjegyű törtmásodpercek megengedettek). A statisztikát a rendszer csak a befejezett kérés összesítéséből számítja ki finished_at; az éppen nyitott perc szándékosan ki van zárva, így az eredmények akár a percösszesítési ütemtől is elmaradhatnak.
average_duration_ms az átlagos teljes Model Gate kérés időtartama (duration_ms) a kiválasztott időszakban teljesített kérések között. Ez nem az E2E első token késleltetése, az upstream első token késleltetése vagy az átjáró overhead. A Partner API csak ezt az explicit metrikanevet fedi fel.
Kér
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_..."Válasz
{
"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"
}
}Kapjon aszinkron eredményt
Kér
curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
-H "Authorization: Bearer mg_partner_..."Válasz feldolgozása
{
"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"
}
}Befejezett válasz
{
"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"
}
}Gyakori hibák
Érvénytelen Partner API kulcs – 401
{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}Az erőforrás nem található – 404
{"error":{"type":"not_found","message":"API key not found"}}Érvénytelen kérelem – 422
{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}A mutáló Partner API JSON-törzs 1 MiB-ra korlátozódik.
Idempotencia konfliktus — 409
Ugyanaz Idempotency-Key újra felhasználták egy másik kérelemhez. Hozzon létre egy új kulcsot egy új logikai művelethez.
Díjkorlát - 429
A válasz tartalmazza error.code = partner_rate_limit_exceeded és Retry-After. Csak a jelzett késleltetés után próbálkozzon újra.
A módszer nem engedélyezett – 405
A partner gazdagép JSON-hibával és HTTP-vel tér vissza Allow fejléc; soha nem esik vissza HTML hibaoldalra.
Üzleti hitelesítési főszabályok
A(z) {0}. számú vállalkozási token esetében csak az ellenőrzött szervezettulajdonos fogadható el. A Partner API által létrehozott kulcsok ezt a tulajdonost használják számlázási tulajdonosként és hitelesítési megbízóként is. Az alkalmazotti és vezetői beosztás a webpanelen történik. group_id, ha megadják, azonosítania kell az üzleti fiókhoz tartozó aktív csoportot; érvénytelen értékek HTTP-t adnak vissza 422 és soha ne essen vissza egy csoportosítatlan kulcshoz. A kéréstörténet-válaszok tartalmazhatnak principal_user_id a hitelesítő megbízó azonosítása a számlázási tulajdonjogtól függetlenül.