Claude Message Batches

As operações existentes de leitura/controle em lote permanecem disponíveis com saldo zero para uma credencial ativa válida, mas POST /v1/messages/batches requer nova admissão de saldo positivo/gastos antes que qualquer linha de trabalho/item seja armazenada. Portanto, uma chave de saldo zero não pode criar um novo lote Claude nem consumir armazenamento de retenção MariaDB. Os itens reais verificam novamente a admissão quando os trabalhadores os reivindicam e aguardam na fila durável se os fundos se esgotarem posteriormente. A entrada é decodificada incrementalmente item por item, em vez de carregada como um documento JSON completo de 256 MB na memória, e as cotas de trabalho ativo/item na fila por usuário vinculam o abuso de armazenamento, independentemente do faturamento.

Model Gate implementa uma API Message Batches compatível com Anthropic em https://api.model-gate.com. É uma camada de compatibilidade: Model Gate armazena o lote de forma durável e executa cada item através do Model Gate normal /v1/messages caminho. Isso acontece não enviar um lote Antrópico nativo do provedor upstream.

Use uma chave de API de modelo normal (mg_live_...). Cada item é contabilizado como uma solicitação individual com request_mode=batch, batch_protocol=claude, o ID do lote e seu custom_id.

O streaming não é compatível dentro de um lote. Os aliases do modelo são resolvidos antes do item ser colocado na fila.

Crie um lote de mensagens

Solicitar

curl https://api.model-gate.com/v1/messages/batches \
  -H "x-api-key: mg_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "summary-1",
        "params": {
          "model": "ch-47",
          "max_tokens": 256,
          "messages": [{"role":"user","content":"Summarize this text."}]
        }
      }
    ]
  }'

Resposta – 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-08-13T08:30:00Z",
  "expires_at": "2026-08-14T08:30:00Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Recuperar um lote

Solicitar

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

Resposta - encerrada

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "ended",
  "request_counts": {
    "processing": 0,
    "succeeded": 1,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": "2026-08-13T08:30:04Z",
  "results_url": "https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results"
}

Ler resultados

Os resultados são retornados como linhas JSON. Não presuma que a lógica do aplicativo depende da ordem de entrada original; combinar resultados por custom_id.

Solicitar

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results \
  -H "x-api-key: mg_live_..."

Resposta – 200

{"custom_id":"summary-1","result":{"type":"succeeded","message":{"id":"msg_...","type":"message","role":"assistant","content":[{"type":"text","text":"..."}]}}}

Listar lotes

limit o padrão é 20 e deve ser de 1 para 100. Usar after_id ou before_id para paginação do cursor; não envie ambos em uma solicitação.

Solicitar

curl "https://api.model-gate.com/v1/messages/batches?limit=20&after_id=msgbatch_01K..." \
  -H "x-api-key: mg_live_..."

Resposta – 200

{
  "data": [],
  "has_more": false,
  "first_id": null,
  "last_id": null
}

Cancelar um lote

Cancelar impede que itens na fila sejam reivindicados. Um item já processado pode terminar.

Solicitar

curl -X POST https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../cancel \
  -H "x-api-key: mg_live_..."

Resposta – 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  }
}

Excluir um lote finalizado

A exclusão é aceita somente depois que o lote atinge um estado terminal.

Solicitar

curl -X DELETE https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

Resposta – 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch_deleted"
}

Semântica de recuperação

Os itens em lote usam a mesma fila durável que as solicitações assíncronas nativas. A recuperação é pelo menos uma vez, não exatamente uma vez: após uma falha do trabalhador, um arrendamento abandonado pode ser recuperado e um item pode ser enviado ao upstream novamente se a primeira resposta do upstream não tiver sido armazenada de forma durável. O ID da solicitação do Model Gate permanece estável durante as novas tentativas e os guardas de liquidação evitam um segundo débito em conta para uma solicitação já concluída.

Cada item é admitido imediatamente antes de um trabalhador reivindicá-lo. Os itens válidos permanecem na fila enquanto o saldo da conta corrente não é positivo ou o limite de gastos redefinível da chave/grupo já está esgotado; esperar por fundos não consome uma tentativa nem marca o item como falha. Uma recarga posterior, redefinição de uso ou aumento de limite retoma automaticamente os itens elegíveis na fila. O Model Gate não reserva o custo do lote do pior caso, portanto, os itens admitidos simultaneamente podem terminar com um saldo final negativo ou uma pequena ultrapassagem do limite de gastos; apenas os novos itens subsequentes são retidos.

Preços e contabilidade

Cada item de lote usa o mesmo roteamento de modelo, contabilidade de token, instantâneo de preços, avaliação de uso, limites de chave/grupo de API e lógica de liquidação que uma solicitação normal de Model Gate. Um administrador pode configurar um Coeficiente de preço de solicitação em lote no modelo de preços da conta. O padrão é 1.

Por exemplo, com custo normal do Model Gate 0.02 e coeficiente de lote 0.5, o débito real da conta é 0.01. O valor de referência salvo do fornecedor oficial não é multiplicado por este coeficiente de lote do Model Gate. Solicitações nativas usando "async": true também não são afetados.

Se o coeficiente diferir de 1, ele é mostrado na página Preços do modelo e em /v1/models como batch_pricing mais o efetivo batch_cost taxas.

Erros

Inválido ou duplicado custom_id, um modelo desconhecido, stream:true, aninhado async:true, uma solicitação superdimensionada ou um corpo inválido retorna uma resposta de erro normal no estilo antrópico.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "summary-1: stream=true is not supported inside a batch"
  }
}