Partner API puntos finales

URL base:

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

Todas las solicitudes requieren:

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

Todos los valores monetarios y límite son cadenas decimales JSON. No los analice como números binarios de punto flotante.

Normas comunes de integración bancaria

Todas las marcas de tiempo externas son UTC RFC3339. Uso de puntos finales de recopilación limit (1–100) más un opaco cursor; nunca analice ni fabrique contenidos del cursor. POST, PATCH, y DELETE las solicitudes requieren Idempotency-Key; Vuelva a intentar la misma operación con la misma clave después de los tiempos de espera. Los registros de idempotencia se conservan durante 7 días. Las respuestas incluyen X-Request-ID, son Cache-Control: no-storey todos los errores son JSON. Las respuestas con límite de velocidad son HTTP 429 con Retry-After y X-RateLimit-* encabezados. Se rechazan los campos de consulta/cuerpo desconocidos.

El contrato OpenAPI 3.1 legible por máquina se distribuye como resources/contracts/partner-api.openapi.yaml.

Crear una clave API

Pedido

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

Respuesta - 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 completo key El valor se devuelve solo después de la creación o rotación.

Listar claves API

Pedido

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

Respuesta: 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 lista se ordena primero como la más nueva y utiliza paginación de cursor opaco. Aprobar limit=1..100; cuando meta.has_more es cierto, envía meta.next_cursor como el siguiente cursor.

Obtenga una clave API

Pedido

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

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

Actualizar una clave API

PATCH reemplaza solo los valores mutables admitidos. Para eliminar la clave de un grupo, envíe un mensaje vacío group_id. Para heredar la configuración de valoración, envíe null para la base y el multiplicador a nivel de clave.

Pedido

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

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

Eliminar una clave API

Pedido

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

Respuesta: 200

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

Congelar y descongelar una clave

Solicitud de congelación

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

Congelar respuesta

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

Solicitud de descongelación

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

Descongelar respuesta

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

La descongelación requiere un correo electrónico del propietario verificado.

Girar una llave

Pedido

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

Respuesta: 200

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

Restablecer el uso de claves

Pedido

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

Respuesta: 200

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

Restablecer el uso no cambia el gasto total ni el saldo de la cuenta.

Obtener uso de claves

Pedido

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

Respuesta: 200

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

Obtener límite de gasto y uso restante

Pedido

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

Respuesta: 200

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

Cuando spend_limit es cero, es ilimitado y remaining es null.

Obtenga las últimas solicitudes de clave

El historial de solicitudes detallado es un conjunto de datos de retención activa controlado por API_REQUESTS_HOT_RETENTION_DAYS (por defecto 7 días). Los metadatos de respuesta informan la ventana de retención activa. Utilice transacciones de saldo para conciliaciones financieras a más largo plazo.

limit es opcional, el valor predeterminado es 10 y debe ser un número entero de 1 a 100. Las solicitudes finalizadas se ordenan por finished_at lo más nuevo primero. Cuando meta.has_more es true, aprobar meta.next_cursor como el opaco before parámetro de consulta para recuperar la siguiente página anterior. No analice ni construya cursores usted mismo.

La respuesta contiene tasas inmutables de usuario y oficiales por millón de tokens para solicitudes completadas después de la migración. 059_request_pricing_audit_snapshot.sql. También calcula pricing_snapshot.usage_price desde la base guardada, el multiplicador y las tasas históricas sin almacenar otro conjunto de tasas. Esto hace que la valoración independiente del límite de uso sea auditable después de que cambian los precios del catálogo. Solicitudes históricas creadas antes del regreso de la migración 059 pricing_snapshot.available: false en lugar de sustituir los precios actuales. Las solicitudes ejecutadas a través de API por lotes compatibles con Claude/OpenAI están marcadas explícitamente con request_mode: "batch" e incluir su protocolo, ID del trabajo por lotes, custom_idy el multiplicador de precios por lotes de Model Gate capturado.

Latencia utiliza nombres estables de negocios/socios: gateway_overhead_ms, upstream_first_token_ms, y e2e_first_token_ms. El valor del primer token E2E se mide desde el inicio de la solicitud de Model Gate hasta el primer token de contenido real y excluye el tiempo TLS/red del lado del cliente. El Partner API expone sólo lo explícito e2e_first_token_ms nombre; la columna de almacenamiento interno permanece api_requests.first_token_ms.

Pedido

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

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

Para continuar con la siguiente 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álido before el cursor devuelve HTTP 422. El cursor contiene sólo la posición de la hora de finalización y el ID público de la solicitud externa; Los ID de solicitud numéricos internos nunca se exponen.

Para solicitudes síncronas y asíncronas nativas, request_mode es sync o async y el batch Se omite el objeto. La instantánea guardada de la tasa de token permite que el cálculo base histórico se reproduzca como sum(tokens × snapshotted_rate / 1,000,000). La liquidación redondea el importe base seleccionado a 10 decimales y luego calcula round(base_amount × multiplier, 10). el almacenado cost, official_base_cost, y usage_cost Los campos siguen siendo autorizados.

Este punto final nunca devuelve los cuerpos de solicitud y respuesta sin procesar.

Listar transacciones de saldo

Pedido

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

Respuesta: 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 inferencia facturable se representa como una fila del libro mayor de billetera por propietario de facturación y minuto de finalización. transaction_id es el identificador duradero del libro mayor público. request_count es el número de solicitudes incluidas en ese minuto de débito; billing_minute_num es floor(unix(finished_at)/60). Libro mayor interno sin procesar id / source_id los valores no se devuelven. Las filas agregadas de uso de API se devuelven intencionalmente null para balance_before, balance_after, y api_key_id; Los detalles exactos de clave/grupo/solicitud permanecen disponibles en el historial de solicitudes y en el desglose de las actas del panel.

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

Utilice este punto final después account.balance_low devoluciones de llamada para conciliar la billetera de la cuenta actual sin requerir una credencial de API modelo.

Listar eventos de auditoría de socios

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

Los eventos de auditoría registran las mutaciones exitosas en la administración de socios con ID de solicitud, acción, destino, IP de origen, estado, metadatos seguros y marca de tiempo UTC. Los secretos, los tokens de portador, el texto sin formato de clave API, las claves de idempotencia, las huellas digitales de solicitud y los cuerpos de reproducción no se almacenan en los metadatos de auditoría. Usar cursor para páginas siguientes y opcional action filtración.

Crear un grupo

Pedido

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

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

Listar grupos

Pedido

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

Respuesta

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

Obtener o actualizar un grupo

Obtener solicitud

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

Obtener respuesta

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

Solicitud de actualización

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

Actualizar respuesta

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

Eliminar un grupo

Un grupo que no esté vacío no se elimina. Mueva o elimine todas las claves API de los miembros primero; de lo contrario, la API devuelve HTTP 409 con group_not_empty.

Pedido

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

Respuesta

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

Las claves se separan según el comportamiento de la clave externa de la base de datos. Verifique la membresía antes de la eliminación.

Restablecer el uso del grupo

Pedido

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

Respuesta

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

Listar miembros del grupo

Pedido

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

Respuesta

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

Agregar una clave a un grupo

Pedido

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

Respuesta

La respuesta es la lista actualizada de miembros del grupo:

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

Eliminar una clave de un grupo

Pedido

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

Respuesta

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

Obtener uso grupal

Pedido

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

Respuesta

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

Obtener estadísticas del grupo

from y to aceptar sólo marcas de tiempo UTC RFC3339 que terminen en Z (Se permiten fracciones de segundo de hasta 6 dígitos). Las estadísticas se calculan únicamente a partir de agregados de solicitudes completadas codificados por finished_at; el minuto actualmente abierto se excluye intencionalmente, por lo que los resultados pueden retrasarse hasta la cadencia de agregación de minutos.

average_duration_ms es la duración promedio completa de la solicitud de Model Gate (duration_ms) entre las solicitudes completadas en el período seleccionado. No se trata de latencia del primer token E2E, latencia del primer token ascendente ni sobrecarga de la puerta de enlace. El Partner API expone solo este nombre de métrica explícito.

Pedido

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

Respuesta

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

Obtener un resultado asincrónico

Pedido

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

Respuesta de procesamiento

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

Respuesta completa

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

Errores comunes

Clave Partner API no válida: 401

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

Recurso no encontrado — 404

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

Solicitud no válida — 422

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

Los cuerpos JSON Partner API mutantes están limitados a 1 MiB.

Conflicto de idempotencia — 409

Lo mismo Idempotency-Key fue reutilizado para una solicitud diferente. Genere una nueva clave para una nueva operación lógica.

Límite de tasa: 429

La respuesta contiene error.code = partner_rate_limit_exceeded y Retry-After. Vuelva a intentarlo sólo después del retraso indicado.

Método no permitido — 405

El host del socio devuelve un error JSON más el HTTP Allow encabezamiento; nunca vuelve a una página de error HTML.

Reglas principales de credenciales comerciales

Para un token de Empresa Partner API, solo se acepta el propietario de la organización verificada. Las claves creadas a través de Partner API utilizan a ese propietario como propietario de facturación y principal de credenciales. La asignación empleado-principal se realiza en el panel web. group_id, cuando se proporciona, debe identificar un grupo activo propiedad de la cuenta comercial; los valores no válidos devuelven HTTP 422 y nunca recurrir a una clave desagrupada. Las respuestas del historial de solicitudes pueden incluir principal_user_id para identificar el principal de la credencial independientemente de la propiedad de facturación.