Processamento em lote é uma abordagem poderosa para lidar com grandes volumes de requisições de forma eficiente. Em vez de processar requisições uma de cada vez com respostas imediatas, o processamento em lote permite que você envie múltiplas requisições juntas para processamento assíncrono. Este padrão é particularmente útil quando:

• Você precisa processar grandes volumes de dados
• Respostas imediatas não são necessárias
• Você quer otimizar para eficiência de custos
• Você está executando avaliações ou análises em larga escala

A API Message Batches é a primeira implementação deste padrão pela Anthropic.

API Message Batches

A API Message Batches é uma forma poderosa e econômica de processar de forma assíncrona grandes volumes de requisições de Messages. Esta abordagem é bem adequada para tarefas que não requerem respostas imediatas, com a maioria dos lotes sendo concluída em menos de 1 hora enquanto reduz custos em 50% e aumenta a taxa de transferência.

Você pode explorar a referência da API diretamente, além deste guia.

Como a API Message Batches funciona

Quando você envia uma requisição para a API Message Batches:

1. O sistema cria um novo Message Batch com as requisições de Messages fornecidas.
2. O lote é então processado de forma assíncrona, com cada requisição sendo tratada independentemente.
3. Você pode fazer polling do status do lote e recuperar resultados quando o processamento tiver terminado para todas as requisições.

Isto é especialmente útil para operações em massa que não requerem resultados imediatos, como:

• Avaliações em larga escala: Processe milhares de casos de teste de forma eficiente.
• Moderação de conteúdo: Analise grandes volumes de conteúdo gerado pelo usuário de forma assíncrona.
• Análise de dados: Gere insights ou resumos para grandes conjuntos de dados.
• Geração de conteúdo em massa: Crie grandes quantidades de texto para vários fins (por exemplo, descrições de produtos, resumos de artigos).

Limitações de lote

• Um Message Batch é limitado a 100.000 requisições de Message ou 256 MB de tamanho, o que for atingido primeiro.
• O sistema processa cada lote o mais rápido possível, com a maioria dos lotes sendo concluída em 1 hora. Você pode acessar resultados de lote quando todas as mensagens tiverem sido concluídas ou após 24 horas, o que vier primeiro. Os lotes expiram se o processamento não for concluído em 24 horas.
• Os resultados do lote estão disponíveis por 29 dias após a criação. Depois disso, você ainda pode visualizar o Batch, mas seus resultados não estarão mais disponíveis para download.
• Os lotes estão no escopo de um Workspace. Você pode visualizar todos os lotes (e seus resultados) que foram criados dentro do Workspace ao qual sua chave de API pertence.
• Os limites de taxa se aplicam tanto às requisições HTTP da API Batches quanto ao número de requisições dentro de um lote aguardando processamento. Veja Limites de taxa da API Message Batches. Além disso, o processamento pode ser desacelerado com base na demanda atual e no volume de suas requisições. Nesse caso, você pode ver mais requisições expirando após 24 horas.
• Devido à alta taxa de transferência e processamento concorrente, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.

Modelos suportados

Todos os modelos ativos suportam a API Message Batches.

O que pode ser colocado em lote

Qualquer requisição que você possa fazer para a API Messages pode ser incluída em um lote. Isto inclui:

• Visão
• Uso de ferramentas
• Mensagens de sistema
• Conversas multi-turno
• Qualquer recurso beta

Como cada requisição no lote é processada independentemente, você pode misturar diferentes tipos de requisições dentro de um único lote.

Preços

A API Batches oferece economias significativas de custos. Todo o uso é cobrado a 50% dos preços padrão da API.

Como usar a API Message Batches

Prepare e crie seu lote

Um Message Batch é composto por uma lista de requisições para criar uma Message. A forma de uma requisição individual é composta por:

• Um custom_id único para identificar a requisição de Messages. Deve ter de 1 a 64 caracteres e conter apenas caracteres alfanuméricos, hífens e sublinhados (correspondendo a ^[a-zA-Z0-9_-]{1,64}$).
• Um objeto params com os parâmetros padrão da API Messages

Você pode criar um lote passando esta lista para o parâmetro requests:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

Neste exemplo, duas requisições separadas são colocadas em lote juntas para processamento assíncrono. Cada requisição tem um custom_id único e contém os parâmetros padrão que você usaria para uma chamada da API Messages.

Quando um lote é criado pela primeira vez, a resposta terá um status de processamento de in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Rastreando seu lote

O campo processing_status do Message Batch indica o estágio de processamento em que o lote se encontra. Começa como in_progress, depois é atualizado para ended uma vez que todas as requisições no lote terminaram o processamento e os resultados estão prontos. Você pode monitorar o estado do seu lote visitando o Console, ou usando o endpoint de recuperação.

Fazendo polling para conclusão do Message Batch

Para fazer polling de um Message Batch, você precisará de seu id, que é fornecido na resposta ao criar um lote ou listando lotes. Você pode implementar um loop de polling que verifica o status do lote periodicamente até que o processamento tenha terminado:

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

Listando todos os Message Batches

Você pode listar todos os Message Batches em seu Workspace usando o endpoint de listagem. A API suporta paginação, buscando automaticamente páginas adicionais conforme necessário:

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recuperando resultados de lote

Após o processamento em lote ter terminado, cada solicitação de Messages no lote tem um resultado. Existem 4 tipos de resultado:

Você verá uma visão geral de seus resultados com request_counts do lote, que mostra quantas solicitações atingiram cada um desses quatro estados.

Os resultados do lote estão disponíveis para download na propriedade results_url no Message Batch e, se a permissão da organização permitir, no Console. Devido ao tamanho potencialmente grande dos resultados, é recomendado transmitir resultados em vez de baixá-los todos de uma vez.

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

Os resultados estão em formato .jsonl, onde cada linha é um objeto JSON válido representando o resultado de uma única solicitação no Message Batch. Para cada resultado transmitido, você pode fazer algo diferente dependendo de seu custom_id e tipo de resultado. Aqui está um exemplo de conjunto de resultados:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Se seu resultado tiver um erro, seu result.error será definido como a forma de erro padrão.

Cancelando um Message Batch

Você pode cancelar um Message Batch que está sendo processado usando o endpoint de cancelamento. Imediatamente após o cancelamento, o processing_status de um lote será canceling. Você pode usar a mesma técnica de polling descrita acima para aguardar até que o cancelamento seja finalizado. Os lotes cancelados terminam com um status de ended e podem conter resultados parciais para solicitações que foram processadas antes do cancelamento.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

A resposta mostrará o lote em um estado canceling:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Usando cache de prompt com Message Batches

A API Message Batches suporta cache de prompt, permitindo que você reduza potencialmente custos e tempo de processamento para solicitações em lote. Os descontos de preço do cache de prompt e Message Batches podem se acumular, proporcionando economias de custo ainda maiores quando ambos os recursos são usados juntos. No entanto, como as solicitações em lote são processadas de forma assíncrona e concorrente, os acertos de cache são fornecidos em base de melhor esforço. Os usuários normalmente experimentam taxas de acerto de cache variando de 30% a 98%, dependendo de seus padrões de tráfego.

Para maximizar a probabilidade de acertos de cache em suas solicitações em lote:

1. Inclua blocos cache_control idênticos em cada solicitação de Message dentro de seu lote
2. Mantenha um fluxo constante de solicitações para evitar que as entradas de cache expirem após seu tempo de vida de 5 minutos
3. Estruture suas solicitações para compartilhar o máximo de conteúdo em cache possível

Exemplo de implementação de cache de prompt em um lote:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Analyze the major themes in Pride and Prejudice.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Write a summary of Pride and Prejudice.",
                    }
                ],
            ),
        ),
    ]
)

Neste exemplo, ambas as solicitações no lote incluem mensagens de sistema idênticas e o texto completo de Pride and Prejudice marcado com cache_control para aumentar a probabilidade de acertos de cache.

Saída estendida (beta)

O cabeçalho beta output-300k-2026-03-24 aumenta o limite de max_tokens para 300.000 para solicitações em lote usando Claude Opus 4.7, Claude Opus 4.6 ou Claude Sonnet 4.6. Inclua o cabeçalho para gerar saídas muito mais longas do que o limite padrão (64k a 128k dependendo do modelo) em uma única volta.

Use saída estendida para geração de longa forma, como rascunhos de livros e documentação técnica, extração de dados estruturados exaustiva, grandes scaffolds de geração de código e cadeias de raciocínio longas.

Uma única geração de 300k tokens pode levar mais de uma hora para ser concluída, então planeje seus envios em lote com a janela de processamento de 24 horas em mente. O preço padrão de lote (50% dos preços padrão da API) se aplica.

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

Melhores práticas para lotes eficazes

Para aproveitar ao máximo a API Batches:

• Monitore regularmente o status de processamento em lote e implemente lógica de repetição apropriada para solicitações com falha.
• Use valores custom_id significativos para corresponder facilmente os resultados com as solicitações, já que a ordem não é garantida.
• Considere dividir conjuntos de dados muito grandes em vários lotes para melhor gerenciabilidade.
• Faça uma execução de teste com uma única forma de solicitação com a API Messages para evitar erros de validação.

Solução de problemas comuns

Se estiver experimentando comportamento inesperado:

• Verifique se o tamanho total da solicitação em lote não excede 256 MB. Se o tamanho da solicitação for muito grande, você pode receber um erro 413 request_too_large.
• Verifique se você está usando modelos suportados para todas as solicitações no lote.
• Certifique-se de que cada solicitação no lote tem um custom_id único.
• Certifique-se de que menos de 29 dias se passaram desde o tempo created_at do lote (não o tempo ended_at de processamento). Se mais de 29 dias se passaram, os resultados não serão mais visualizáveis.
• Confirme que o lote não foi cancelado.

Observe que a falha de uma solicitação em um lote não afeta o processamento de outras solicitações.

Armazenamento e privacidade de lotes

• Isolamento de espaço de trabalho: Os lotes são isolados dentro do Workspace em que foram criados. Eles só podem ser acessados por chaves de API associadas a esse Workspace ou por usuários com permissão para visualizar lotes do Workspace no Console.

• Disponibilidade de resultados: Os resultados do lote estão disponíveis por 29 dias após a criação do lote, permitindo tempo amplo para recuperação e processamento.

Retenção de dados

O processamento em lote armazena dados de solicitação e resposta por até 29 dias após a criação do lote. Você pode excluir um lote de mensagens a qualquer momento após o processamento usando o endpoint DELETE /v1/messages/batches/{batch_id}. Para excluir um lote em andamento, cancele-o primeiro. O processamento assíncrono requer armazenamento no servidor de entradas e saídas até a conclusão do lote e recuperação de resultados.

Para elegibilidade de ZDR em todos os recursos, consulte Retenção de API e dados.

Perguntas frequentes