Message Batches na Claude API: quando vale mandar tarefas em lote e pagar metade

Fala aí, beleza? Na hora de escolher entre Sonnet 5.5 e Opus 5.5, o critério costuma ser o tipo de tarefa, qual modelo encara melhor cada coisa

Aqui o critério é outro: a URGÊNCIA da resposta 🙂

Tem chamada que precisa voltar agora, porque tem alguém olhando pra tela, e tem chamada que pode esperar umas horas sem ninguém nem perceber

Esse critério vale pros dois modelos, e é ele que decide se a tarefa roda em tempo real ou em lote na Claude API

Como funciona a Message Batches API da Claude

Você junta várias requisições num lote só e manda tudo de uma vez, e a Anthropic processa cada uma de forma independente e assíncrona

Aí, em vez de esperar a resposta na hora, você fica consultando o status do lote (o famoso polling) e baixa os resultados quando todas as requisições terminarem

A referência de tudo isso é a documentação oficial de batch processing

Pra que serve o custom_id?

Cada requisição do lote leva um custom_id que você mesmo define, e ele precisa ser único dentro do lote

E por que isso importa? Porque os resultados podem voltar fora de ordem

Sem um custom_id bem pensado, tu recebe um monte de respostas e não sabe qual é de qual haha

Tome cuidado aqui: use algo que aponte direto pro dado de origem (o id do produto, do ticket, do caso de teste e por aí vai)

Em que formato chegam os resultados?

Os resultados vêm em .jsonl, que é um objeto JSON por linha, um pra cada requisição

Eles ficam disponíveis no campo results_url do lote, e a documentação recomenda baixar em streaming, porque o arquivo pode ficar grande

Cada linha traz um destes tipos de resultado:

• succeeded: a requisição deu certo
• errored: deu erro
• canceled: foi cancelada
• expired: não foi processada dentro do prazo

Ou seja, o lote não é tudo ou nada, você precisa tratar cada linha pelo tipo dela 😀

Quais são os limites de um lote: tamanho, prazo e retenção

Cada lote aceita até 100.000 requisições ou 256 MB, o que for atingido primeiro

Se a sua carga passa disso, é dividir em mais de um lote

Quanto tempo um lote demora?

Segundo a documentação, a maioria dos lotes termina em menos de 1 hora

Mas a janela máxima é de 24 horas: os resultados ficam acessíveis quando todas as mensagens terminam ou depois de 24 horas, o que acontecer primeiro

E se não der tempo? As requisições que não foram processadas até o fim das 24 horas recebem o status expired e não são cobradas

Então o planejamento tem que contar com o pior caso, não com o "geralmente termina rápido"…

Por quanto tempo dá pra baixar os resultados?

Os resultados ficam disponíveis por 29 dias após a criação do lote

Depois disso o lote ainda aparece, mas os resultados não podem mais ser baixados

Já vi muita gente deixar arquivo "pra baixar depois" e esquecer, então se liga: baixa e guarda do teu lado

Saída longa no Sonnet 5.5

Pela Message Batches API, o Claude Sonnet 5.5 aceita até 300 mil tokens de saída com o cabeçalho beta output-300k-2026-03-24, segundo a página oficial de preços

Isso é útil quando cada requisição precisa gerar um texto bem grande

Quanto custa em lote: Sonnet 5.5 e Opus 5.5, preço padrão x Batch

O lote dá 50% de desconto sobre os preços padrão da API, e o desconto vale pros tokens de entrada, de saída e qualquer token especial

Os valores abaixo são da página oficial de preços, por milhão de tokens (MTok):

Modelo	Entrada padrão	Saída padrão	Entrada em lote	Saída em lote
Claude Sonnet 5.5	US$ 2	US$ 10	US$ 1	US$ 5
Claude Opus 5.5	US$ 4	US$ 20	US$ 2	US$ 10

Se liga nesse detalhe: o Opus 5.5 em lote custa exatamente o mesmo que o Sonnet 5.5 no modo padrão (US$ 2 de entrada e US$ 10 de saída por MTok)

Isso não quer dizer que o Opus seja a escolha certa pra tudo, a decisão de modelo continua sendo pela tarefa

Mas abre uma possibilidade massa: se o trabalho pede o Opus e não tem pressa, rodar em lote deixa ele com preço de Sonnet padrão

Dá para somar Batch e cache de prompt?

Dá sim! A documentação confirma que a Message Batches API suporta cache de prompt e que os descontos dos dois se acumulam

Se você ainda não domina essa parte, vale entender antes como funciona o cache de prompt na Claude API

Os multiplicadores padrão do cache, sempre em relação ao preço base de entrada, são estes:

• Gravação no cache de 5 minutos: 1,25x
• Gravação no cache de 1 hora: 2x
• Leitura (acerto de cache): 0,1x

Qual a pegadinha do cache em lote?

Em lote, o acerto de cache é entregue na base do melhor esforço, porque as requisições rodam de forma assíncrona e simultânea

A documentação diz que a taxa de acerto costuma ficar entre 30% e 98%, conforme o padrão de tráfego, e não tem garantia

Por isso não dá pra cravar uma economia final: a conta muda totalmente dependendo de quantas requisições acertam o cache

Como melhorar o aproveitamento do cache no lote?

A documentação dá duas orientações:

• Incluir blocos cache_control idênticos em todas as requisições do lote
• Manter um fluxo constante de requisições, pra que as entradas de 5 minutos não expirem

E tem mais uma: como um lote pode levar mais de 5 minutos pra processar, a documentação sugere usar a duração de cache de 1 hora quando as requisições compartilham contexto

Só lembra que a gravação no cache de 1 hora custa 2x a entrada base, então ela faz sentido quando o contexto repetido é grande e vai ser reaproveitado de verdade

Quando usar Batch e quando não usar

Use lote quando o resultado pode chegar depois e o volume é grande

Evite quando alguém está esperando a resposta ou quando o próximo passo depende da saída anterior

Casos que combinam com lote

A documentação oficial cita estes use cases:

• Avaliações em larga escala, com milhares de casos de teste, como rodar a mesma bateria contra várias versões de um prompt
• Moderação de conteúdo
• Análise de dados, tirando insights ou resumos de grandes conjuntos de dados
• Geração de conteúdo em massa, como descrições de produto e resumos de artigos

Classificação em volume entra na mesma lógica: rotular milhares de tickets, comentários ou registros que ninguém precisa ver classificados no segundo seguinte

Casos em que o lote atrapalha

• Chat: o usuário está ali digitando e esperando, não dá pra pedir que ele volte em algumas horas haha
• Agente interativo: cada passo depende do resultado do anterior, e o lote processa as requisições de forma independente
• Qualquer fluxo encadeado, em que a saída de uma chamada vira a entrada da próxima

O motivo é sempre o mesmo: o processamento é assíncrono, e o prazo pode chegar a 24 horas

Tempo real ou lote: como decidir pela urgência

O veredito depende do teu cenário, mas dá pra resumir em três perguntas

Alguém está esperando a resposta? Se não, e o volume é alto, manda em lote e paga metade

A tarefa é interativa ou encadeada? Se sim, fica no tempo real, sem discussão

O lote repete um contexto grande em todas as requisições? Aí vale combinar com cache de 1 hora, sabendo que o acerto não é garantido

E a escolha do modelo? É uma decisão separada: primeiro tu decide Sonnet ou Opus pela tarefa, depois decide tempo real ou lote pela urgência

As duas decisões se combinam, uma não substitui a outra

Falando em dividir trabalho entre modelos, no vídeo abaixo o assunto é outro jeito de organizar isso, só que dentro do Claude Code: o Opus coordena e o Haiku executa

Próximo passo: separar o que é urgente do que pode esperar

Pega as chamadas que o teu sistema faz hoje (as que saem com a tua chave de API da Claude) e marca uma por uma: tem usuário esperando ou não?

Classificação, resumos, avaliações de prompt e geração em massa costumam cair no "não", e essas são as candidatas a lote

Antes de migrar, confere duas coisas:

1. Se o volume de cada lote cabe em 100.000 requisições ou 256 MB, e divide se passar
2. Como vai montar o custom_id, pra conseguir casar cada resultado com o dado de origem mesmo com tudo voltando fora de ordem

Feito isso, começa por uma tarefa só e acompanha os tipos de resultado que voltam no .jsonl

Até o próximo post! 🙂

Perguntas frequentes

A Message Batches API funciona com qualquer modelo Claude?

Os valores confirmados neste post cobrem o Claude Sonnet 5.5 e o Claude Opus 5.5, com preço padrão e preço em lote pra cada um. Pra outros modelos, o caminho é checar a página oficial de preços antes de montar o lote.

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.