O 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. Esse padrão é particularmente útil quando:

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

A API de Lotes de Mensagens é a primeira implementação da Anthropic desse padrão.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

API de Lotes de Mensagens

A API de Lotes de Mensagens é uma forma poderosa e econômica de processar de forma assíncrona grandes volumes de requisições de Mensagens. Essa abordagem é bem adequada para tarefas que não exigem respostas imediatas, com a maioria dos lotes sendo concluída em menos de 1 hora, reduzindo os custos em 50% e aumentando o throughput.

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

Como a API de Lotes de Mensagens funciona

Quando você envia uma requisição para a API de Lotes de Mensagens:

O sistema cria um novo Lote de Mensagens com as requisições de Mensagens fornecidas.
O lote é então processado de forma assíncrona, com cada requisição tratada de forma independente.
Você pode verificar o status do lote e recuperar os resultados quando o processamento de todas as requisições tiver terminado.

Isso é especialmente útil para operações em massa que não exigem 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 por usuários 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 lotes

Um Lote de Mensagens é limitado a 100.000 requisições de Mensagens 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ê poderá acessar os resultados do lote quando todas as mensagens forem concluídas ou após 24 horas, o que ocorrer primeiro. Os lotes expirarão se o processamento não for concluído em 24 horas.
Os resultados do lote ficam disponíveis por 29 dias após a criação. Depois disso, você ainda pode visualizar o Lote, mas seus resultados não estarão mais disponíveis para download.
Os lotes têm escopo para um Workspace. Você pode visualizar todos os lotes (e seus resultados) que foram criados no Workspace ao qual sua chave de API pertence.
Os limites de taxa se aplicam tanto às requisições HTTP da API de Lotes quanto ao número de requisições dentro de um lote aguardando processamento. Consulte Limites de taxa da API de Lotes de Mensagens. Além disso, o processamento pode ser desacelerado com base na demanda atual e no volume de requisições. Nesse caso, você pode ver mais requisições expirando após 24 horas.
Devido ao alto throughput e processamento simultâneo, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.

Modelos suportados

Todos os modelos ativos suportam a API de Lotes de Mensagens.

O que pode ser processado em lote

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

Visão
Uso de ferramentas
Mensagens de sistema
Conversas de múltiplos turnos
Quaisquer recursos beta

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

Como os lotes podem levar mais de 5 minutos para serem processados, considere usar a duração de cache de 1 hora com cache de prompt para melhores taxas de acerto de cache ao processar lotes com contexto compartilhado.

Preços

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5

Como usar a API de Lotes de Mensagens

Prepare e crie seu lote

Um Lote de Mensagens é composto por uma lista de requisições para criar uma Mensagem. A estrutura de uma requisição individual é composta por:

Um custom_id único para identificar a requisição de Mensagens
Um objeto params com os parâmetros padrão da API de Mensagens

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

Neste exemplo, duas requisições separadas são agrupadas em lote 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 de Mensagens.

Teste suas requisições de lote com a API de Mensagens

A validação do objeto params para cada requisição de mensagem é realizada de forma assíncrona, e os erros de validação são retornados quando o processamento de todo o lote termina. Você pode garantir que está construindo sua entrada corretamente verificando o formato da sua requisição com a API de Mensagens primeiro.

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

JSON

{
  "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
}

Acompanhando seu lote

O campo processing_status do Lote de Mensagens indica o estágio de processamento em que o lote se encontra. Ele começa como in_progress, depois é atualizado para ended assim que todas as requisições no lote terminam de ser processadas e os resultados estão prontos. Você pode monitorar o estado do seu lote visitando o Console ou usando o endpoint de recuperação.

Verificando a conclusão do Lote de Mensagens por polling

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

Listando todos os Lotes de Mensagens

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

Recuperando resultados do lote

Quando o processamento do lote terminar, cada requisição de Mensagens no lote terá um resultado. Existem 4 tipos de resultado:

Tipo de Resultado	Descrição
`succeeded`	A requisição foi bem-sucedida. Inclui o resultado da mensagem.
`errored`	A requisição encontrou um erro e uma mensagem não foi criada. Os possíveis erros incluem requisições inválidas e erros internos do servidor. Você não será cobrado por essas requisições.
`canceled`	O usuário cancelou o lote antes que esta requisição pudesse ser enviada ao modelo. Você não será cobrado por essas requisições.
`expired`	O lote atingiu sua expiração de 24 horas antes que esta requisição pudesse ser enviada ao modelo. Você não será cobrado por essas requisições.

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

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

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

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","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-6","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 o seu resultado tiver um erro, seu result.error será definido com o formato de erro padrão.

Os resultados do lote podem não corresponder à ordem de entrada

Os resultados do lote podem ser retornados em qualquer ordem e podem não corresponder à ordem das requisições quando o lote foi criado. No exemplo acima, o resultado da segunda requisição do lote é retornado antes do primeiro. Para corresponder corretamente os resultados com suas requisições correspondentes, sempre use o campo custom_id.

Cancelando um Lote de Mensagens

Você pode cancelar um Lote de Mensagens 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 requisições que foram processadas antes do cancelamento.

A resposta mostrará o lote em um estado canceling:

JSON

{
  "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 de Message Batches suporta cache de prompt, permitindo que você potencialmente reduza custos e tempo de processamento para requisições em lote. Os descontos de preço do cache de prompt e dos Message Batches podem se acumular, proporcionando economias de custo ainda maiores quando ambos os recursos são usados juntos. No entanto, como as requisições em lote são processadas de forma assíncrona e concorrente, os acertos de cache são fornecidos com base no 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 requisições em lote:

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

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

Neste exemplo, ambas as requisiçõ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.

Melhores práticas para um loteamento eficaz

Para aproveitar ao máximo a API de Batches:

Monitore o status de processamento do lote regularmente e implemente lógica de repetição adequada para requisições com falha.
Use valores custom_id significativos para combinar facilmente resultados com requisições, já que a ordem não é garantida.
Considere dividir conjuntos de dados muito grandes em múltiplos lotes para melhor gerenciamento.
Execute um teste com uma única forma de requisição com a API de Messages para evitar erros de validação.

Solução de problemas comuns

Se estiver experimentando comportamento inesperado:

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

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

Armazenamento e privacidade de lotes

Isolamento de Workspace: 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 ficam disponíveis por 29 dias após a criação do lote, permitindo tempo suficiente para recuperação e processamento.

Retenção de dados

O processamento em lote armazena dados de requisiçã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}. O processamento assíncrono requer armazenamento no lado do servidor tanto de entradas quanto de saídas até a conclusão do lote e a recuperação dos resultados.

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

Perguntas frequentes

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

import anthropic
import time

client = anthropic.Anthropic()

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)

import anthropic

client = anthropic.Anthropic()

# Busca automaticamente mais páginas conforme necessário.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # O corpo da requisição deve ser corrigido antes de reenviar a requisição
            echo "Validation error: $custom_id"
          else
            # A requisição pode ser reenviada diretamente
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "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."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "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."}
                ]
            }
        }
    ]
}'

Processamento em lote

Processamento em lote

API de Lotes de Mensagens

Como a API de Lotes de Mensagens funciona

Limitações de lotes

Modelos suportados

O que pode ser processado em lote

Preços

Como usar a API de Lotes de Mensagens

Prepare e crie seu lote

Acompanhando seu lote

Verificando a conclusão do Lote de Mensagens por polling

Listando todos os Lotes de Mensagens

Recuperando resultados do lote

Cancelando um Lote de Mensagens

Usando cache de prompt com Message Batches

Melhores práticas para um loteamento eficaz

Solução de problemas comuns

Armazenamento e privacidade de lotes

Retenção de dados

Perguntas frequentes

API de Lotes de Mensagens

Como a API de Lotes de Mensagens funciona

Limitações de lotes

Modelos suportados

O que pode ser processado em lote

Preços

Como usar a API de Lotes de Mensagens

Prepare e crie seu lote

Acompanhando seu lote

Verificando a conclusão do Lote de Mensagens por polling

Listando todos os Lotes de Mensagens

Recuperando resultados do lote

Cancelando um Lote de Mensagens

Usando cache de prompt com Message Batches

Melhores práticas para um loteamento eficaz

Solução de problemas comuns

Armazenamento e privacidade de lotes

Retenção de dados

Perguntas frequentes

Quanto tempo leva para um lote ser processado?

A API de Batches está disponível para todos os modelos?

Posso usar a API de Message Batches com outros recursos da API?

Como a API de Message Batches afeta os preços?

Posso atualizar um lote após ele ter sido enviado?

Existem limites de taxa da API de Message Batches e eles interagem com os limites de taxa da API de Messages?

Como lidar com erros nas minhas requisições em lote?

Como a API de Message Batches lida com privacidade e separação de dados?

Posso usar cache de prompt na API de Message Batches?