Partner API punts finals

URL base:

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

Totes les peticions requereixen:

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

Tots els valors monetaris i límit són cadenes decimals JSON. No els analitzis com a nombres binaris de coma flotant.

Normes comunes d'integració del banc

Totes les marques de temps externes són UTC RFC3339. Ús dels punts finals de la col·lecció limit (1–100) més un opac cursor; mai analitzeu ni fabriqueu el contingut del cursor. POST, PATCH, i DELETE les peticions requereixen Idempotency-Key; Torneu a provar la mateixa operació amb la mateixa clau després d'esperar el temps d'espera. Els registres d'idempotència es conserven durant 7 dies. Les respostes inclouen X-Request-ID, són Cache-Control: no-store, i tots els errors són JSON. Les respostes amb límit de velocitat són HTTP 429 amb Retry-After i X-RateLimit-* capçaleres. Es rebutgen els camps del cos/de la consulta desconeguts.

El contracte OpenAPI 3.1 llegible per màquina es distribueix com resources/contracts/partner-api.openapi.yaml.

Creeu una clau API

Sol·licitud

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

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

El complet key el valor només es retorna després de la creació o la rotació.

Llista les claus de l'API

Sol·licitud

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

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

La llista s'ordena primer i fa servir la paginació opaca del cursor. Passa limit=1..100; quan meta.has_more és veritat, envia meta.next_cursor com el següent cursor.

Obteniu una clau API

Sol·licitud

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

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

Actualitza una clau API

PATCH substitueix només els valors mutables admesos. Per eliminar la clau d'un grup, envieu-ne una buida group_id. Per heretar la configuració de la valoració, envieu null per a la base de nivell de clau i el multiplicador.

Sol·licitud

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

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

Suprimeix una clau d'API

Sol·licitud

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

Resposta: 200

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

Congela i descongela una clau

Sol·licitud de congelació

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

Congela la resposta

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

Sol·licitud de descongelació

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

Descongela la resposta

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

La descongelació requereix un correu electrònic del propietari verificat.

Gira una tecla

Sol·licitud

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

Resposta: 200

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

Restableix l'ús de la clau

Sol·licitud

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

Resposta: 200

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

Restablir l'ús no canvia la despesa de tota la vida ni el saldo del compte.

Obteniu l'ús de les claus

Sol·licitud

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

Resposta: 200

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

Obteniu el límit de despesa i l'ús restant

Sol·licitud

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

Resposta: 200

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

Quan spend_limit és zero, és il·limitat i remaining és null.

Obteniu les últimes sol·licituds d'una clau

L'historial de sol·licituds detallat és un conjunt de dades de retenció en calent controlat per API_REQUESTS_HOT_RETENTION_DAYS (per defecte 7 dies). Les metadades de la resposta informen de la finestra de retenció activa. Utilitzeu transaccions de saldo per a una conciliació financera a llarg termini.

limit és opcional, el valor predeterminat és 10 i ha de ser un nombre enter entre 1 i 100. Les sol·licituds finalitzades s'ordenen per finished_at el més nou primer. Quan meta.has_more és true, passar meta.next_cursor com l'opac before paràmetre de consulta per recuperar la següent pàgina anterior. No analitzeu ni construïu cursors vosaltres mateixos.

La resposta conté tarifes immutables d'usuari i per milió de testimoni oficials per a les sol·licituds completades després de la migració 059_request_pricing_audit_snapshot.sql. També calcula pricing_snapshot.usage_price des de la base desada, el multiplicador i les tarifes històriques sense emmagatzemar un altre conjunt de tarifes. Això fa que la valoració del límit d'ús independent sigui auditable després que canviïn els preus del catàleg. Sol·licituds històriques creades abans del retorn de la migració 059 pricing_snapshot.available: false en lloc de substituir els preus actuals. Les sol·licituds executades mitjançant API de lots compatibles amb Claude/OpenAI es marquen explícitament amb request_mode: "batch" i incloure el seu protocol, ID de treball per lots, custom_id, i el multiplicador de preus per lots de Model Gate de la instantània.

La latència utilitza noms estables d'empresa/soci: gateway_overhead_ms, upstream_first_token_ms, i e2e_first_token_ms. El valor del primer testimoni E2E es mesura des de l'inici de la sol·licitud de Model Gate fins al primer testimoni de contingut real i exclou el temps de xarxa/TLS del costat del client. El Partner API només exposa l'explícit e2e_first_token_ms nom; roman la columna d'emmagatzematge intern api_requests.first_token_ms.

Sol·licitud

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

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

Per continuar amb la següent pàgina anterior:

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

Un invàlid before el cursor retorna HTTP 422. El cursor conté només la posició de l'hora d'arribada i l'identificador públic de la sol·licitud externa; Els identificadors de sol·licitud numèrics interns no s'exposen mai.

Per a sol·licituds síncrones i natives asíncrones, request_mode és sync o async i el batch s'omet l'objecte. La instantània de la taxa de testimoni desada permet reproduir el càlcul històric de la base com a sum(tokens × snapshotted_rate / 1,000,000). La liquidació arrodoneix la quantitat base seleccionada a 10 decimals i després calcula round(base_amount × multiplier, 10). L'emmagatzemat cost, official_base_cost, i usage_cost camps segueixen sent autoritat.

Aquest punt final no retorna mai els cossos de sol·licitud i resposta en brut.

Llista de transaccions de saldo

Sol·licitud

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

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

La inferència facturable es representa com una fila del llibre de cartera per propietari de facturació i minut de finalització. transaction_id és l'identificador durador del llibre major públic. request_count és el nombre de peticions incloses en aquest minut de dèbit; billing_minute_num és floor(unix(finished_at)/60). Llibre interior en brut id / source_id no es retornen els valors. Les files d'ús de l'API agregades tornen intencionadament null per balance_before, balance_after, i api_key_id; Els detalls exactes de la clau/grup/sol·licitud romanen disponibles a l'historial de sol·licituds i al detall del minut del panell.

Obteniu el saldo actual

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

Feu servir aquest punt final després account.balance_low devolució de trucades per conciliar la cartera del compte actual sense requerir una credencial de l'API Model.

Llista els esdeveniments d'auditoria de socis

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

Els esdeveniments d'auditoria registren mutacions reeixides de gestió de partners amb l'identificador de sol·licitud, l'acció, l'objectiu, la IP d'origen, l'estat, les metadades segures i la marca de temps UTC. Els secrets, els testimonis del portador, el text sense format de la clau API, les claus d'idempotència, les empremtes dactilars de sol·licitud i els cossos de reproducció no s'emmagatzemen a les metadades d'auditoria. Ús cursor per a pàgines següents i opcional action filtració.

Crear un grup

Sol·licitud

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

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

Llista de grups

Sol·licitud

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

Resposta

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

Obteniu o actualitzeu un grup

Obteniu la sol·licitud

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

Obteniu resposta

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

Sol·licitud d'actualització

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

Actualitza la resposta

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

Suprimeix un grup

Un grup no buit no s'elimina. Primer moure o suprimir totes les claus de l'API dels membres; en cas contrari, l'API retorna HTTP 409 amb group_not_empty.

Sol·licitud

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

Resposta

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

Les claus es deslliguen segons el comportament de la clau estrangera de la base de dades. Verifiqueu la pertinença abans de suprimir-lo.

Restableix l'ús del grup

Sol·licitud

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

Resposta

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

Llista els membres del grup

Sol·licitud

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

Resposta

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

Afegeix una clau a un grup

Sol·licitud

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

Resposta

La resposta és la llista actualitzada de membres del grup:

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

Eliminar una clau d'un grup

Sol·licitud

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

Resposta

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

Obteniu l'ús del grup

Sol·licitud

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

Resposta

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

Obteniu estadístiques de grup

from i to accepteu només les marques de temps UTC RFC3339 que acabin en Z (es permeten fraccions de segons fins a 6 dígits). Les estadístiques només es calculen a partir dels agregats de sol·licituds completades amb clau finished_at; el minut obert actualment s'exclou intencionadament, de manera que els resultats poden retardar fins a la cadència d'agregació del minut.

average_duration_ms és la durada mitjana completa de la sol·licitud de Model Gate (duration_ms) a les sol·licituds completades durant el període seleccionat. No és la latència del primer testimoni E2E, la latència del primer testimoni aigües amunt ni la sobrecàrrega de la passarel·la. El Partner API només exposa aquest nom de mètrica explícit.

Sol·licitud

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

Resposta

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

Obteniu un resultat asíncron

Sol·licitud

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

Processament de la resposta

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

Resposta completada

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

Errors comuns

Clau Partner API no vàlida: 401

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

No s'ha trobat el recurs — 404

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

Sol·licitud no vàlida: 422

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

Els cossos JSON que muten Partner API estan limitats a 1 MiB.

Conflicte d'idempotència - 409

El mateix Idempotency-Key s'ha reutilitzat per a una sol·licitud diferent. Genereu una nova clau per a una nova operació lògica.

Límit de tarifa: 429

La resposta conté error.code = partner_rate_limit_exceeded i Retry-After. Torna-ho a provar només després del retard indicat.

Mètode no permès - 405

L'amfitrió del partner retorna un error JSON més l'HTTP Allow capçalera; mai torna a una pàgina d'error HTML.

Regles principals de credencials empresarials

Per a un testimoni d'empresa núm.{0}, només s'accepta el propietari verificat de l'organització. Les claus creades mitjançant Partner API utilitzen aquest propietari com a propietari de facturació i com a principal de credencials. L'assignació de l'empleat-director es realitza al tauler web. group_id, quan es proporcioni, ha d'identificar un grup actiu propietat del compte d'empresa; els valors no vàlids retornen HTTP 422 i mai tornar a una clau no agrupada. Les respostes de l'historial de sol·licituds poden incloure principal_user_id per identificar el principal de la credencial independentment de la propietat de la facturació.