Arquivos e lotes

Criar Lote de Mensagens

Cria um lote de solicitações de Mensagens que são executadas de forma assíncrona.

POST
/v1/messages/batches

Visão geral

Envie até 100.000 solicitações de Mensagens em uma única chamada. O lote é executado de forma assíncrona. A resposta é retornada imediatamente com processing_status definido como in_progress. Recupere o lote até que ele esteja ended, então obtenha os resultados.

Notas

  • Cada item em requests possui um custom_id e params. params aceita os mesmos campos que Criar Mensagem, incluindo max_tokens. Os itens não podem usar speed: "fast".
  • custom_id deve ter de 1 a 64 letras, dígitos, sublinhados ou hifens, e deve ser único dentro do lote.
  • Todos os modelos no lote devem estar disponíveis para lotes. O TokenLab rejeita toda a solicitação com 400 quando um modelo não está disponível, ou quando nenhuma rota única pode atender a todos os modelos no lote.
  • O TokenLab reserva o custo estimado ao aceitar o lote e retorna 402 quando o saldo não é suficiente para cobri-lo. Após o término do lote, o TokenLab liquida o uso das solicitações que tiveram sucesso. Os preços de lote podem diferir dos preços síncronos.
  • Se um item fizer referência ao conteúdo de file_id, envie anthropic-beta: files-api-2025-04-14.
  • Envie um Idempotency-Key para repetir uma solicitação de criação que excedeu o tempo limite com segurança. Veja Repetir com segurança usando uma chave de idempotência.

Exemplo

Requisição

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

Exemplo de resposta

Resposta

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

Campos importantes

idstring
ID do lote de mensagens. Use-o para recuperar, cancelar ou excluir o lote e para obter seus resultados.
processing_statusstring
in_progress, canceling ou ended.
request_countsobject
Número de solicitações que estão processing, succeeded, errored, canceled ou expired.
expires_atstring
Quando o lote expira. As solicitações que não tiverem terminado até lá serão finalizadas como expired.
results_urlstring|null
URL dos resultados. É null até que o lote tenha terminado.

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Chave opcional que torna uma requisição de criação segura para novas tentativas. Envie um novo valor único, como um UUID, para cada tarefa. Uma nova tentativa com a mesma chave e o mesmo corpo retorna o resultado da requisição de criação original, geralmente a tarefa original, e não cria, despacha ou cobra uma segunda tarefa. Um corpo diferente com uma chave que já foi aceita é rejeitado com 409. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json