B2BB2B LLM

Partner API pontos de extremidade

Conclua Partner API exemplos de solicitação e resposta para chaves, grupos, solicitações e transações.

Partner API pontos de extremidade

URL base:

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

Todas as solicitações exigem:

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

Todos os valores monetários e limites são strings decimais JSON. Não os analise como números binários de ponto flutuante.

Regras comuns de integração bancária

Todos os carimbos de data/hora externos são UTC RFC3339. Uso de endpoints de coleta limit (1–100) mais um opaco cursor; nunca analise ou fabrique o conteúdo do cursor. POST, PATCH, e DELETE solicitações exigem Idempotency-Key; tente novamente a mesma operação com a mesma chave após o tempo limite. Os registros de idempotência são retidos por 7 dias. As respostas incluem X-Request-ID, são Cache-Control: no-storee todos os erros são JSON. As respostas com limite de taxa são HTTP 429 com Retry-After e X-RateLimit-* cabeçalhos. Campos de corpo/consulta desconhecidos são rejeitados.

O contrato OpenAPI 3.1 legível por máquina é distribuído como resources/contracts/partner-api.openapi.yaml.

Crie uma chave de API

Solicitar

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

O completo key o valor é retornado somente após a criação ou rotação.

Listar chaves de API

Solicitar

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

A lista é ordenada mais recente primeiro e usa paginação de cursor opaco. Passar limit=1..100; quando meta.has_more é verdade, envie meta.next_cursor como o próximo cursor.

Obtenha uma chave de API

Solicitar

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

Atualizar uma chave de API

PATCH substitui apenas os valores mutáveis ​​suportados. Para remover a chave de um grupo, envie um vazio group_id. Para herdar configurações de avaliação, envie null para a base e o multiplicador de nível-chave.

Solicitar

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

Excluir uma chave de API

Solicitar

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

Congelar e descongelar uma chave

Solicitação de congelamento

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

Resposta congelada

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

Solicitação de descongelamento

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

Resposta descongelar

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

O descongelamento requer um e-mail de proprietário verificado.

Girar uma chave

Solicitar

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

Redefinir o uso da chave

Solicitar

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

A redefinição do uso não altera o gasto vitalício nem o saldo da conta.

Obtenha o uso da chave

Solicitar

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

Obtenha limite de gastos e uso restante

Solicitar

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

Quando spend_limit é zero, é ilimitado e remaining é null.

Receba as últimas solicitações de uma chave

O histórico detalhado de solicitações é um conjunto de dados de retenção a quente controlado por API_REQUESTS_HOT_RETENTION_DAYS (padrão 7 dias). Os metadados de resposta informam a janela de retenção ativa. Use transações de saldo para reconciliação financeira de longo prazo.

limit é opcional, o padrão é 10 e deve ser um número inteiro de 1 a 100. As solicitações finalizadas são ordenadas por finished_at mais novo primeiro. Quando meta.has_more é true, passar meta.next_cursor como o opaco before parâmetro de consulta para recuperar a próxima página mais antiga. Não analise ou construa cursores sozinho.

A resposta contém taxas imutáveis ​​de usuários e oficiais por milhão de tokens para solicitações concluídas após a migração 059_request_pricing_audit_snapshot.sql. Também calcula pricing_snapshot.usage_price da base salva, multiplicador e taxas históricas sem armazenar outro conjunto de taxas. Isso torna a avaliação independente do limite de uso auditável após a alteração dos preços de catálogo. Solicitações históricas criadas antes do retorno da migração 059 pricing_snapshot.available: false em vez de substituir os preços actuais. As solicitações executadas por meio de APIs em lote compatíveis com Claude/OpenAI são explicitamente marcadas com request_mode: "batch" e inclua seu protocolo, ID do trabalho em lote, custom_ide o multiplicador de preço do lote do Model Gate capturado.

A latência usa nomes de empresas/parceiros estáveis: gateway_overhead_ms, upstream_first_token_ms, e e2e_first_token_ms. O valor do primeiro token E2E é medido desde o início da solicitação do Model Gate até o primeiro token de conteúdo real e exclui o tempo de rede/TLS do lado do cliente. O Partner API expõe apenas o explícito e2e_first_token_ms nome; a coluna de armazenamento interno permanece api_requests.first_token_ms.

Solicitar

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

Para continuar com a próxima página mais antiga:

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

Um inválido before cursor retorna HTTP 422. O cursor contém apenas a posição do horário de término e o ID público da solicitação externa; IDs de solicitação numéricos internos nunca são expostos.

Para solicitações assíncronas síncronas e nativas, request_mode é sync ou async e o batch objeto é omitido. O instantâneo salvo da taxa de token permite que o cálculo da base histórica seja reproduzido como sum(tokens × snapshotted_rate / 1,000,000). A liquidação arredonda o valor base selecionado para 10 casas decimais e depois calcula round(base_amount × multiplier, 10). O armazenado cost, official_base_cost, e usage_cost os campos permanecem oficiais.

Os corpos brutos de solicitação e resposta nunca são retornados por esse endpoint.

Listar transações de saldo

Solicitar

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

A inferência faturável é representada como uma linha do livro-razão da carteira por proprietário de cobrança e minuto de término. transaction_id é o identificador do razão público durável. request_count é o número de solicitações incluídas naquele débito minuto; billing_minute_num é floor(unix(finished_at)/60). Razão interna bruta id / source_id os valores não são retornados. Linhas agregadas de uso de API retornam intencionalmente null para balance_before, balance_after, e api_key_id; os detalhes exatos da chave/grupo/solicitação permanecem disponíveis no histórico de solicitações e no detalhamento de minutos do painel.

Obtenha saldo atual

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

Use este endpoint depois account.balance_low retornos de chamada para reconciliar a carteira da conta atual sem exigir uma credencial da API do modelo.

Listar eventos de auditoria de parceiros

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

Os eventos de auditoria registram mutações bem-sucedidas de gerenciamento de parceiros com ID de solicitação, ação, destino, IP de origem, status, metadados seguros e carimbo de data/hora UTC. Segredos, tokens de portador, texto simples da chave de API, chaves de idempotência, impressões digitais de solicitação e corpos de reprodução não são armazenados em metadados de auditoria. Usar cursor para páginas subsequentes e opcional action filtragem.

Crie um grupo

Solicitar

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

Listar grupos

Solicitar

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

Obtenha ou atualize um grupo

Obter solicitação

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

Obter resposta

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

Solicitação de atualização

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

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

Excluir um grupo

Um grupo não vazio não é excluído. Mova ou exclua todas as chaves de API dos membros primeiro; caso contrário, a API retornará HTTP 409 com group_not_empty.

Solicitar

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

As chaves são desanexadas de acordo com o comportamento da chave estrangeira do banco de dados. Verifique a associação antes da exclusão.

Redefinir o uso do grupo

Solicitar

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

Listar membros do grupo

Solicitar

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

Adicionar uma chave a um grupo

Solicitar

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

A resposta é a lista atualizada de membros do grupo:

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

Remover uma chave de um grupo

Solicitar

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

Obter uso do grupo

Solicitar

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

Obtenha estatísticas do grupo

from e to aceita apenas carimbos de data/hora UTC RFC3339 terminando em Z (frações de segundos de até 6 dígitos são permitidas). As estatísticas são calculadas apenas a partir de agregados de solicitações concluídas codificados por finished_at; o minuto atualmente aberto é excluído intencionalmente, portanto os resultados podem atrasar até a cadência de agregação do minuto.

average_duration_ms é a duração média completa da solicitação do Model Gate (duration_ms) em solicitações concluídas no período selecionado. Não é a latência do primeiro token E2E, a latência do primeiro token upstream ou a sobrecarga do gateway. O Partner API expõe apenas esse nome de métrica explícito.

Solicitar

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

Obtenha um resultado assíncrono

Solicitar

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

Processando 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 concluída

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

Erros comuns

Chave Partner API inválida — 401

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

Recurso não encontrado — 404

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

Solicitação inválida — 422

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

A mutação de Partner API corpos JSON é limitada a 1 MiB.

Conflito de idempotência - 409

O mesmo Idempotency-Key foi reutilizado para uma solicitação diferente. Gere uma nova chave para uma nova operação lógica.

Limite de taxa – 429

A resposta contém error.code = partner_rate_limit_exceeded e Retry-After. Tente novamente somente após o atraso indicado.

Método não permitido — 405

O host do parceiro retorna um erro JSON mais o HTTP Allow cabeçalho; ele nunca volta para uma página de erro HTML.

Regras principais de credenciais comerciais

Para um token Business Partner API, apenas o proprietário verificado da organização é aceito. As chaves criadas por meio de Partner API usam esse proprietário como proprietário de cobrança e principal da credencial. A atribuição funcionário-principal é realizada no painel web. group_id, quando fornecido, deve identificar um grupo ativo pertencente à conta Empresarial; valores inválidos retornam HTTP 422 e nunca volte para uma chave desagrupada. As respostas do histórico de solicitações podem incluir principal_user_id para identificar o principal da credencial independentemente da propriedade da cobrança.