O processamento em lote é uma abordagem poderosa para lidar com grandes volumes de solicitações de forma eficiente. Em vez de processar solicitações uma de cada vez com respostas imediatas, o processamento em lote permite que você envie múltiplas solicitaçõ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 é nossa primeira implementação deste padrão.

​

API Message Batches

A API Message Batches é uma maneira poderosa e econômica de processar assincronamente grandes volumes de solicitações de Messages. Esta abordagem é adequada para tarefas que não requerem respostas imediatas, com a maioria dos lotes terminando em menos de 1 hora enquanto reduz custos em 50% e aumenta o throughput.

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

​

Como a API Message Batches funciona

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

1. O sistema cria um novo Message Batch com as solicitações Messages fornecidas.
2. O lote é então processado assincronamente, com cada solicitação tratada independentemente.
3. Você pode fazer polling do status do lote e recuperar resultados quando o processamento terminar para todas as solicitações.

Isso é 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 eficientemente.
• Moderação de conteúdo: Analise grandes volumes de conteúdo gerado pelo usuário assincronamente.
• 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 propósitos (por exemplo, descrições de produtos, resumos de artigos).

​

Limitações do lote

• Um Message Batch é limitado a 100.000 solicitações Message ou 256 MB de tamanho, o que for atingido primeiro.
• Processamos cada lote o mais rápido possível, com a maioria dos lotes completando dentro de 1 hora. Você poderá acessar os resultados do lote quando todas as mensagens tiverem sido completadas ou após 24 horas, o que vier primeiro. Os lotes expirarão se o processamento não for concluído dentro de 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 Lote, mas seus resultados não estarão mais disponíveis para download.
• Os lotes são limitados a um Workspace. Você pode visualizar todos os lotes—e seus resultados—que foram criados dentro do Workspace ao qual sua chave API pertence.
• Limites de taxa se aplicam tanto às solicitações HTTP da API Batches quanto ao número de solicitações dentro de um lote aguardando processamento. Veja limites de taxa da API Message Batches. Além disso, podemos desacelerar o processamento com base na demanda atual e no volume de suas solicitações. Nesse caso, você pode ver mais solicitações expirando após 24 horas.
• Devido ao alto throughput e processamento concorrente, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.

​

Modelos suportados

A API Message Batches atualmente suporta:

• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
• Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 e claude-3-5-sonnet-20241022)
• Claude Haiku 3.5 (claude-3-5-haiku-20241022)
• Claude Haiku 3 (claude-3-haiku-20240307)
• Claude Opus 3 (claude-3-opus-20240229)

​

O que pode ser processado em lote

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

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

Como cada solicitação no lote é processada independentemente, você pode misturar diferentes tipos de solicitaçõ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 solicitações para criar uma Message. A forma de uma solicitação individual é composta por:

• Um custom_id único para identificar a solicitação Messages
• 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:

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-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

Neste exemplo, duas solicitações separadas são agrupadas em lote para processamento assíncrono. Cada solicitaçã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 está. Começa como in_progress, depois atualiza para ended uma vez que todas as solicitações no lote terminaram de processar, e os resultados estão prontos. Você pode monitorar o estado do seu lote visitando o Console, ou usando o endpoint de recuperação:

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'

Você pode fazer polling deste endpoint para saber quando o processamento terminou.

​

Recuperando resultados do lote

Uma vez que o processamento do lote terminou, cada solicitação Messages no lote terá um resultado. Há 4 tipos de resultado:

Você verá uma visão geral dos seus resultados com o 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 do Message Batch, e se a permissão da organização permitir, no Console. Devido ao tamanho potencialmente grande dos resultados, é recomendado fazer stream dos resultados de volta em vez de baixá-los todos de uma vez.

#!/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
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

Os resultados estarão no 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 do 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-20250514","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-20250514","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 para nossa forma de erro padrão.

​

Usando cache de prompt com Message Batches

A API Message Batches suporta cache de prompt, permitindo que você potencialmente reduza custos e tempo de processamento para solicitações de lote. Os descontos de preços do cache de prompt e Message Batches podem se acumular, fornecendo economias de custos ainda maiores quando ambos os recursos são usados juntos. No entanto, como as solicitações de lote são processadas assincronamente e concorrentemente, 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 solicitações de lote:

1. Inclua blocos cache_control idênticos em cada solicitação Message dentro do seu lote
2. Mantenha um fluxo constante de solicitações para evitar que 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:

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-20250514",
                "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-20250514",
                "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.

​

Melhores práticas para loteamento eficaz

Para obter o máximo da API Batches:

• Monitore o status de processamento do lote regularmente e implemente lógica de retry apropriada para solicitações falhadas.
• Use valores custom_id significativos para facilmente corresponder resultados com solicitações, já que a ordem não é garantida.
• Considere quebrar conjuntos de dados muito grandes em múltiplos lotes para melhor gerenciabilidade.
• Execute um teste seco de uma única forma de solicitação com a API Messages para evitar erros de validação.

​

Solucionando problemas comuns

Se experimentar comportamento inesperado:

• Verifique se o tamanho total da solicitação do 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.
• Garanta que cada solicitação no lote tenha um custom_id único.
• Garanta que tenham se passado menos de 29 dias desde o tempo created_at do lote (não o ended_at do 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.

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

​

Armazenamento e privacidade do lote

• Isolamento do workspace: Os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por chaves API associadas a esse Workspace, ou 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 o lote ser criado, permitindo tempo amplo para recuperação e processamento.

​

FAQ