Partner API krajnje točke
Ispunite Partner API primjere zahtjeva i odgovora za ključeve, grupe, zahtjeve i transakcije.
Partner API krajnje točke
Osnovni URL:
https://p-api.model-gate.com
Svi zahtjevi zahtijevaju:
Authorization: Bearer mg_partner_...
Accept: application/json
Sve monetarne i granične vrijednosti su JSON decimalni nizovi. Nemojte ih analizirati kao binarne brojeve s pomičnim zarezom.
Zajednička pravila integracije Banke
Sve vanjske vremenske oznake su UTC RFC3339. Upotreba krajnjih točaka zbirke limit (1–100) plus neprozirni cursor; nikada ne analizirajte niti proizvodite sadržaj kursora. POST, PATCH, i DELETE zahtjevi zahtijevaju Idempotency-Key; ponovite istu operaciju s istim ključem nakon isteka vremena. Idempotency records are retained for 7 days. Odgovori uključuju X-Request-ID, su Cache-Control: no-store, a sve pogreške su JSON. Odgovori ograničenja brzine su HTTP 429 s Retry-After i X-RateLimit-* zaglavlja. Nepoznato tijelo/polja upita se odbijaju.
Strojno čitljiv OpenAPI 3.1 ugovor distribuira se kao resources/contracts/partner-api.openapi.yaml.
Izradite API ključ
Zahtjev
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"
}'
Odgovor — 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"
}
}
Kompletan key vrijednost se vraća samo nakon stvaranja ili rotacije.
Navedite API ključeve
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/keys \
-H "Authorization: Bearer mg_partner_..."
Odziv — 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"
}
]
}
Popis je poredan prvo najnovijim i koristi neprozirnu paginaciju kursora. Proći limit=1..100; kada meta.has_more je istina, pošalji meta.next_cursor kao sljedeći cursor.
Nabavite jedan API ključ
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."
Odziv — 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"
}
}
Ažurirajte API ključ
PATCH zamjenjuje samo podržane promjenjive vrijednosti. Za uklanjanje ključa iz grupe pošaljite prazan group_id. Da biste naslijedili postavke vrednovanja, pošaljite null za bazu i množitelj na razini ključa.
Zahtjev
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
}'
Odziv — 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"
}
}
Izbrišite API ključ
Zahtjev
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" \
Odziv — 200
{"data":{"deleted":true}}
Zamrzavanje i odmrzavanje ključa
Zahtjev za zamrzavanje
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" \
Zamrzni odgovor
{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}
Zahtjev za odmrzavanje
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" \
Odmrzni odgovor
{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}
Odmrzavanje zahtijeva potvrđenu e-poštu vlasnika.
Okrenite ključ
Zahtjev
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" \
Odziv — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"status": "active",
"key_prefix": "mg_live_cd34",
"key": "mg_live_cd34..."
}
}
Ponovno postavljanje ključa
Zahtjev
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" \
Odziv — 200
{
"data": {
"public_id": "KEY_PUBLIC_ID",
"usage": "0.0000000000",
"total_spent": "1.1400000000"
}
}
Ponovno postavljanje upotrebe ne mijenja doživotnu potrošnju ili stanje računa.
Dobijte korištenje ključa
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."
Odziv — 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"usage": "3.2500000000",
"total_spent": "1.1400000000"
}
}
Dobijte ograničenje potrošnje i preostalu upotrebu
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
-H "Authorization: Bearer mg_partner_..."
Odziv — 200
{
"data": {
"key_id": "KEY_PUBLIC_ID",
"spend_limit": "20.0000000000",
"usage": "3.2500000000",
"remaining": "16.7500000000"
}
}
Kada spend_limit je nula, neograničeno je i remaining je null.
Dobijte najnovije zahtjeve za ključ
Detaljna povijest zahtjeva skup je podataka koji se čuva u radnom stanju kojim upravlja API_REQUESTS_HOT_RETENTION_DAYS (zadano 7 dana). Metapodaci odgovora izvješćuju o aktivnom vremenskom okviru zadržavanja. Koristite bilančne transakcije za dugoročnije financijsko usklađivanje.
limit nije obavezan, zadana vrijednost je 10 i mora biti cijeli broj od 1 do 100. Finalizirani zahtjevi su poredani prema finished_at prvo najnoviji. Kada meta.has_more je true, prolaz meta.next_cursor kao neproziran before parametar upita za dohvaćanje sljedeće starije stranice. Nemojte sami analizirati ili konstruirati kursore.
Odgovor sadrži nepromjenjive korisničke i službene stope po milijun tokena za zahtjeve dovršene nakon migracije 059_request_pricing_audit_snapshot.sql. Također izračunava pricing_snapshot.usage_price iz spremljene osnove, množitelja i povijesnih stopa bez pohranjivanja drugog skupa stopa. To čini nezavisnu procjenu ograničenja upotrebe revizijskom nakon promjene kataloških cijena. Povijesni zahtjevi stvoreni prije povratka migracije 059 pricing_snapshot.available: false a ne supstitucijom trenutnih cijena. Zahtjevi koji se izvršavaju putem batch API-ja kompatibilnih s Claude/OpenAI izričito su označeni s request_mode: "batch" i uključuju njihov protokol, ID skupnog posla, custom_idi multiplikator skupne cijene Model Gate snimljen na slici.
Latencija koristi stabilne nazive tvrtki/partnera: gateway_overhead_ms, upstream_first_token_ms, i e2e_first_token_ms. Vrijednost E2E prvog tokena mjeri se od početka zahtjeva Model Gate do prvog tokena stvarnog sadržaja i isključuje mrežno/TLS vrijeme na strani klijenta. Partner API izlaže samo eksplicitno e2e_first_token_ms ime; interni stupac za pohranu ostaje api_requests.first_token_ms.
Zahtjev
curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
-H "Authorization: Bearer mg_partner_..."
Odziv — 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
}
}
Da biste nastavili sa sljedećom starijom stranicom:
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_..."
Invalid before kursor vraća HTTP 422. Kursor sadrži samo poziciju vremena završetka i javni ID vanjskog zahtjeva; interni numerički ID-ovi zahtjeva nikada nisu izloženi.
Za sinkrone i izvorne asinkrone zahtjeve, request_mode je sync ili async i batch objekt je izostavljen. Spremljena snimka stope tokena omogućuje reprodukciju povijesnog osnovnog izračuna kao sum(tokens × snapshotted_rate / 1,000,000). Obračun zaokružuje odabrani osnovni iznos na 10 decimalnih mjesta i zatim izračunava round(base_amount × multiplier, 10). Pohranjeni cost, official_base_cost, i usage_cost polja ostaju mjerodavna.
Ova krajnja točka nikada ne vraća neobrađena tijela zahtjeva i odgovora.
Popis stanja transakcija
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/transactions \
-H "Authorization: Bearer mg_partner_..."
Odziv — 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"
}
]
}
Zaključak o naplati predstavljen je kao jedan red knjige novčanika po vlasniku naplate i minuti završetka. transaction_id je trajni identifikator javne knjige. request_count je broj zahtjeva uključenih u to minutno zaduženje; billing_minute_num je floor(unix(finished_at)/60). Neobrađena interna knjiga id / source_id vrijednosti se ne vraćaju. Skupni reci upotrebe API-ja namjerno se vraćaju null za balance_before, balance_after, i api_key_id; točan detalj o ključu/grupi/zahtjevu ostaje dostupan iz povijesti zahtjeva i detaljnog pregleda minuta panela.
Dobiti trenutno stanje
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"}}
Koristite ovu krajnju točku nakon account.balance_low povratne pozive za usklađivanje lisnice trenutnog računa bez potrebe za model API vjerodajnicama.
Navedite događaje revizije partnera
curl "https://p-api.model-gate.com/api/v1/partner/audit-events?limit=100" \
-H "Authorization: Bearer mg_partner_..."
Događaji revizije bilježe uspješne mutacije upravljanja partnerima s ID-om zahtjeva, radnjom, ciljem, izvornim IP-om, statusom, sigurnim metapodacima i vremenskom oznakom UTC. Tajne, tokeni nositelja, otvoreni tekst API-ključa, ključevi idempotencije, otisci prstiju zahtjeva i tijela za ponavljanje nisu pohranjeni u metapodacima revizije. Koristiti cursor za sljedeće stranice i izborno action filtriranje.
Napravite grupu
Zahtjev
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"
}'
Odgovor — 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"
}
}
Popis grupa
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/groups \
-H "Authorization: Bearer mg_partner_..."
Odgovor
{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}
Nabavite ili ažurirajte grupu
Dobiti zahtjev
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
-H "Authorization: Bearer mg_partner_..."
Dobiti odgovor
{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}
Zahtjev za ažuriranje
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"}'
Ažuriraj odgovor
{"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"}}
Brisanje grupe
Grupa koja nije prazna se ne briše. Najprije premjestite ili izbrišite sve članske API ključeve; inače API vraća HTTP 409 s group_not_empty.
Zahtjev
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" \
Odgovor
{"data":{"deleted":true}}
Ključevi se odvajaju prema ponašanju stranog ključa baze podataka. Potvrdite članstvo prije brisanja.
Poništi korištenje grupe
Zahtjev
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" \
Odgovor
{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}
Navedite članove grupe
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
-H "Authorization: Bearer mg_partner_..."
Odgovor
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}
Dodajte ključ grupi
Zahtjev
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"}'
Odgovor
Odgovor je ažurirani popis članova grupe:
{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active"}]}
Uklonite ključ iz grupe
Zahtjev
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" \
Odgovor
{"data":{"removed":true}}
Dobijte grupno korištenje
Zahtjev
curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
-H "Authorization: Bearer mg_partner_..."
Odgovor
{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}
Dobijte grupnu statistiku
from i to prihvati samo UTC RFC3339 vremenske oznake koje završavaju s Z (dopušteni su razlomci sekundi do 6 znamenki). Statistika se izračunava samo iz agregata dovršenih zahtjeva unesenih ključem finished_at; trenutna otvorena minuta namjerno je isključena, tako da rezultati mogu kasniti do ritma agregacije minuta.
average_duration_ms je prosječno puno trajanje zahtjeva Model Gate (duration_ms) preko ispunjenih zahtjeva u odabranom razdoblju. To nije E2E kašnjenje prvog tokena, uzvodno kašnjenje prvog tokena ili opterećenje pristupnika. Partner API izlaže samo ovaj izričiti naziv metrike.
Zahtjev
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_..."
Odgovor
{
"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"
}
}
Dobijte asinkroni rezultat
Zahtjev
curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
-H "Authorization: Bearer mg_partner_..."
Obrada odgovora
{
"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"
}
}
Dovršen odgovor
{
"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"
}
}
Uobičajene pogreške
Nevažeći ključ Partner API — 401
{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}
Resurs nije pronađen — 404
{"error":{"type":"not_found","message":"API key not found"}}
Neispravan zahtjev — 422
{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}
Mutirajuća Partner API JSON tijela ograničena su na 1 MiB.
Sukob idempotencije — 409
Isti Idempotency-Key ponovno je korišten za drugi zahtjev. Generirajte novi ključ za novu logičku operaciju.
Ograničenje brzine — 429
Odgovor sadrži error.code = partner_rate_limit_exceeded i Retry-After. Pokušajte ponovno tek nakon naznačenog kašnjenja.
Metoda nije dopuštena — 405
Host partnera vraća JSON grešku plus HTTP Allow zaglavlje; nikad se ne vraća na stranicu s HTML pogreškom.
Pravila voditelja poslovne vjerodajnice
Za Business Partner API token prihvaća se samo potvrđeni vlasnik organizacije. Ključevi stvoreni pomoću Partner API koriste tog vlasnika i kao vlasnika naplate i kao glavnog vjerodajnika. Raspoređivanje zaposlenika i ravnatelja vrši se u web panelu. group_id, kada se isporuči, mora identificirati aktivnu grupu u vlasništvu poslovnog računa; nevažeće vrijednosti vraćaju HTTP 422 i nikada se ne vraćajte na negrupirani ključ. Odgovori povijesti zahtjeva mogu uključivati principal_user_id za identifikaciju glavnog vjerodajnika neovisno o vlasništvu nad naplatom.