Solicitações assíncronas

O modo assíncrono do Model Gate armazena um trabalho de inferência na fila MariaDB durável e retorna imediatamente um ID de solicitação. Independente sub2proxy os trabalhadores reivindicam trabalhos na fila com concessões, e as concessões abandonadas podem ser recuperadas após a reinicialização do processo. O resultado concluído é lido do Partner API ou entregue ao callback configurado no Perfil.

O modo assíncrono é compatível com:

• POST /v1/chat/completions
• POST /v1/messages
• POST /v1/responses
• POST /v1/images/generations

Solicitações assíncronas não podem usar stream: true.

Solicitação de fila

Adicione a extensão Model Gate "async": true para uma solicitação válida.

Solicitar

curl https://api.model-gate.com/v1/responses \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Write a short release summary.",
    "async": true,
    "stream": false
  }'

Resposta - 202

{
  "request_id": "01KZ...",
  "status": "queued",
  "result_url": "https://p-api.model-gate.com/api/v1/requests/01KZ..."
}

O async O campo é removido antes que a solicitação seja enviada ao upstream. Um alias de modelo é resolvido para seu modelo canônico antes da tarefa ser colocada na fila. O trabalhador revalida a chave e executa por meio do mesmo núcleo de solicitação/contabilidade do Model Gate que a inferência síncrona. As linhas da fila não contêm segredo de chave de API. O preço assíncrono nativo permanece inalterado e não usa o coeficiente de preço de solicitação em lote.

Antes de um trabalhador reivindicar um item, ele verifica o saldo da conta atual e o uso atual de gastos de chave/grupo redefiníveis no MariaDB. Se o saldo da conta não for positivo ou se um limite de gastos de chave/grupo configurado já estiver esgotado, o item permanecerá queued e não consome uma tentativa de execução. Uma recarga posterior, uma redefinição de uso ou um aumento de limite tornam o item elegível automaticamente. O Model Gate não reserva um custo estimado de solicitação: o trabalho que já foi aprovado na admissão pode ser concluído e liquidado seu custo real completo, mesmo quando o trabalho simultâneo torna o saldo final negativo ou excede ligeiramente o limite de gastos. Novas execuções são então bloqueadas até que a conta seja elegível novamente.

Semântica de recuperação

A fila durável fornece recuperação pelo menos uma vez, não exatamente uma vez. Se um processo de trabalho parar depois que um provedor upstream aceitou uma solicitação, mas antes que o Model Gate armazene de forma durável o resultado assíncrono, a concessão eventualmente expirará e outro trabalhador poderá tentar novamente o mesmo ID de solicitação do Model Gate. A liquidação é protegida contra débito duplo, mas os aplicativos que causam efeitos colaterais externos por meio de ferramentas de modelo devem tornar esses efeitos colaterais idempotentes.

Recuperar resultado

Use uma chave Partner API pertencente à mesma conta Model Gate.

Solicitar

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

Resposta - processamento

{
  "data": {
    "request_id": "01KZ...",
    "status": "processing",
    "created_at": "2026-08-05 10:00:00",
    "started_at": "2026-08-05 10:00:01",
    "completed_at": null,
    "expires_at": "2026-08-06 10:00:00"
  }
}

Resposta - concluída

{
  "data": {
    "request_id": "01KZ...",
    "status": "completed",
    "response_status": 200,
    "response_headers": {
      "content-type": ["application/json"]
    },
    "response": {
      "id": "resp_...",
      "object": "response",
      "status": "completed"
    },
    "created_at": "2026-08-05 10:00:00",
    "started_at": "2026-08-05 10:00:01",
    "completed_at": "2026-08-05 10:00:03",
    "expires_at": "2026-08-06 10:00:00"
  }
}

O endpoint de resultado retorna o corpo upstream completo armazenado até expires_at. Um ID de solicitação estrangeiro, expirado ou desconhecido retorna 404.

Erros

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_async_stream_combination",
    "message": "Async requests cannot be streamed."
  }
}

Retorno de endpoints não suportados async_not_supported.

Retornos de chamada

Os resultados assíncronos concluídos são enfileirados de forma durável para entrega na URL de retorno de chamada configurada no Perfil. A entrega de retorno de chamada tem sua própria fila de trabalho/nova tentativa e, portanto, não espera por outra solicitação da Model API. A manutenção também reconcilia linhas assíncronas do terminal no histórico de solicitações e recupera um retorno de chamada de conclusão ausente após uma falha do trabalhador. Ver Retornos de chamada para verificação de assinatura, novas tentativas e orientação de idempotência.