--- title: Processamento em lote url: https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing description: Processe grandes volumes de requisições de Messages de forma assíncrona com a Message Batches API, reduzindo custos em 50% e aumentando a taxa de transferência. --- O "batch processing" (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 várias 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 Message Batches API é a primeira implementação desse padrão pela Anthropic. Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention). # Message Batches API A Message Batches API é uma forma poderosa e econômica de processar de forma assíncrona grandes volumes de requisições de [Messages](https://platform.claude.com/docs/pt-BR/api/messages/create). Essa abordagem é adequada para tarefas que não exigem respostas imediatas, com a maioria dos lotes sendo concluída em menos de 1 hora, ao mesmo tempo em que reduz os custos em 50% e aumenta a taxa de transferência. Você pode [explorar a referência da API diretamente](https://platform.claude.com/docs/pt-BR/api/messages/batches/create), além deste guia. ## Como a Message Batches API funciona Quando você envia uma requisição para a Message Batches API: 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 tratada de forma independente. 3. Você pode consultar o status do lote e recuperar os resultados quando o processamento tiver terminado para todas as requisições. 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 diversos fins (por exemplo, descrições de produtos, resumos de artigos). ### Limitações de lotes * 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 até 1 hora. Você pode acessar os resultados do lote quando todas as mensagens tiverem sido concluídas ou após 24 horas, o que ocorrer primeiro. Os lotes expiram 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 poderá visualizar o Batch, mas seus resultados não estarão mais disponíveis para download. * Os lotes têm escopo de um [Workspace](https://platform.claude.com/settings/workspaces). Você pode visualizar todos os lotes (e seus resultados) que foram criados dentro do Workspace em que sua requisição é executada. * Os "rate limits" (limites de taxa) se aplicam tanto às requisições HTTP da Batches API quanto ao número de requisições dentro de um lote aguardando processamento. Consulte [limites de taxa da Message Batches API](https://platform.claude.com/docs/pt-BR/api/rate-limits#message-batches-api). Além disso, o processamento pode ser desacelerado com base na demanda atual e no seu volume de requisições. Nesse caso, você pode ver mais requisições expirando após 24 horas. * Devido à alta taxa de transferência e ao processamento concorrente, os lotes podem ultrapassar ligeiramente o [limite de gastos](https://platform.claude.com/settings/billing) configurado do seu Workspace. * Cada requisição em lote deve ter `max_tokens` de pelo menos `1`. `max_tokens: 0` ([pré-aquecimento do cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pre-warming-the-cache)) não é suportado dentro de um lote, porque uma entrada de cache efêmera gravada durante o processamento do lote provavelmente expiraria antes que a requisição subsequente fosse executada. ### Modelos suportados Todos os [modelos ativos](https://platform.claude.com/docs/pt-BR/models/overview) suportam a Message Batches API. ### O que pode ser processado em lote Quase qualquer requisição que você pode fazer à Messages API pode ser incluída em um lote. Isso inclui: * Visão * "Tool use" (uso de ferramentas), incluindo todas as [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) (busca na web, busca de conteúdo web, execução de código, conectores MCP, advisor e busca de ferramentas) * Mensagens de sistema * Conversas de múltiplos turnos * "Extended thinking" (pensamento estendido) * A maioria dos recursos beta Como cada requisição no lote é processada de forma independente, você pode misturar diferentes tipos de requisições em um único lote. Um pequeno número de parâmetros da Messages API **não** é suportado em requisições em lote. Incluir qualquer um deles retorna um erro de validação: | Parâmetro | Motivo | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `stream: true` | Os resultados do lote são retornados como um único arquivo, não como um stream. | | `speed` ([modo rápido](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode)) | O modo rápido ajusta a "latency" (latência) síncrona, o que não se aplica ao processamento assíncrono em lote. | | `max_tokens: 0` | Consulte [Limitações dos lotes](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#batch-limitations). | Como os lotes podem levar mais de 5 minutos para serem processados, considere usar a [duração de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) com cache de prompt para obter melhores taxas de acerto de cache ao processar lotes com contexto compartilhado. ## Preços A Batches API oferece economias de custo significativas. Todo o uso é cobrado a 50% dos preços padrão da API. | Model | Batch input | Batch output | | :-------------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ | | Claude Fable 5.1 | $5 / MTok | $25 / MTok | | Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok | | Claude Fable 5 | $5 / MTok | $25 / MTok | | Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok | | Claude Opus 5.5 | $2 / MTok | $10 / MTok | | Claude Opus 5 | $2.50 / MTok | $12.50 / MTok | | Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok | | Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok | | Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok | | Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok | | Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok | | Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok | | Claude Sonnet 5.5 | $1 / MTok | $5 / MTok | | Claude Sonnet 5 | $1 / MTok | $5 / MTok | | Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok | | Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok | | Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok | | Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.05 / MTok | $0.25 / MTok | | Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.25 / MTok | $1.25 / MTok | | Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok | | Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $0.40 / MTok | $2 / MTok | * **MTok:** Million tokens. $5 / MTok is $5 for every million tokens. * **Limited access:** Available only to organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). To request access, apply to the program that covers your use case. * **Retired:** May still be available on other cloud platforms. See [Model deprecations](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations) for more. ## Como usar a Message Batches API ### Prepare e crie seu lote Um Message Batch é composto por uma lista de requisições para criar uma Message. O formato de uma requisição individual compreende: * 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 [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create) Você pode [criar um lote](https://platform.claude.com/docs/pt-BR/api/messages/batches/create) passando essa lista no parâmetro `requests`: ```bash cURL 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-5-5", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello, world"} ] } }, { "custom_id": "my-second-request", "params": { "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hi again, friend"} ] } } ] }' ``` ```bash CLI ant messages:batches create <<'YAML' requests: - custom_id: my-first-request params: model: claude-opus-5-5 max_tokens: 1024 messages: - role: user content: Hello, world - custom_id: my-second-request params: model: claude-opus-5-5 max_tokens: 1024 messages: - role: user content: Hi again, friend YAML ``` ```python Python 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-5-5", max_tokens=1024, messages=[ { "role": "user", "content": "Hello, world", } ], ), ), Request( custom_id="my-second-request", params=MessageCreateParamsNonStreaming( model="claude-opus-5-5", max_tokens=1024, messages=[ { "role": "user", "content": "Hi again, friend", } ], ), ), ] ) print(message_batch) ``` ```typescript TypeScript const client = new Anthropic(); const messageBatch = await client.messages.batches.create({ requests: [ { custom_id: "my-first-request", params: { model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, world" }] } }, { custom_id: "my-second-request", params: { model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hi again, friend" }] } } ] }); console.log(messageBatch); ``` ```csharp C# using Anthropic; using Anthropic.Models.Messages; using Anthropic.Models.Messages.Batches; AnthropicClient client = new(); var batch = await client.Messages.Batches.Create(new BatchCreateParams { Requests = [ new() { CustomID = "my-first-request", Params = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "Hello, world" } ] } }, new() { CustomID = "my-second-request", Params = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "Hi again, friend" } ] } } ] }); Console.WriteLine(batch); ``` ```go Go client := anthropic.NewClient() batch, _ := client.Messages.Batches.New(context.Background(), anthropic.MessageBatchNewParams{ Requests: []anthropic.MessageBatchNewParamsRequest{ { CustomID: "my-first-request", Params: anthropic.MessageBatchNewParamsRequestParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage( anthropic.NewTextBlock("Hello, world"), ), }, }, }, { CustomID: "my-second-request", Params: anthropic.MessageBatchNewParamsRequestParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage( anthropic.NewTextBlock("Hi again, friend"), ), }, }, }, }, }) fmt.Println(batch.ID) ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BatchCreateParams params = BatchCreateParams.builder() .addRequest( BatchCreateParams.Request.builder() .customId("my-first-request") .params( BatchCreateParams.Request.Params.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello, world") .build() ) .build() ) .addRequest( BatchCreateParams.Request.builder() .customId("my-second-request") .params( BatchCreateParams.Request.Params.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hi again, friend") .build() ) .build() ) .build(); MessageBatch messageBatch = client.messages().batches().create(params); System.out.println(messageBatch); ``` ```php PHP $client = new Client(); $batch = $client->messages->batches->create( requests: [ [ 'custom_id' => 'my-first-request', 'params' => [ 'model' => 'claude-opus-5-5', 'max_tokens' => 1024, 'messages' => [ ['role' => 'user', 'content' => 'Hello, world'] ] ] ], [ 'custom_id' => 'my-second-request', 'params' => [ 'model' => 'claude-opus-5-5', 'max_tokens' => 1024, 'messages' => [ ['role' => 'user', 'content' => 'Hi again, friend'] ] ] ] ], ); echo $batch->id; ``` ```ruby Ruby client = Anthropic::Client.new batch = client.messages.batches.create( requests: [ { custom_id: "my-first-request", params: { model: "claude-opus-5-5", max_tokens: 1024, messages: [ { role: "user", content: "Hello, world" } ] } }, { custom_id: "my-second-request", params: { model: "claude-opus-5-5", max_tokens: 1024, messages: [ { role: "user", content: "Hi again, friend" } ] } } ] ) puts batch ``` 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 à Messages API. **Teste suas requisições em lote com a Messages API** 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 tiver terminado. Você pode garantir que está construindo sua entrada corretamente verificando o formato da sua requisição com a [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create) primeiro. Quando um lote é criado pela primeira vez, a resposta tem um status de processamento `in_progress`. ```json Output { "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 Message Batch indica o estágio de processamento em que o lote se encontra. Ele começa como `in_progress`, depois é atualizado para `ended` quando todas as requisições no lote tiverem terminado de ser processadas e os resultados estiverem prontos. Você pode monitorar o estado do seu lote visitando o [Console](https://platform.claude.com/settings/workspaces/default/batches) ou usando o [endpoint de recuperação](https://platform.claude.com/docs/pt-BR/api/messages/batches/retrieve). #### Consultando a conclusão do Message Batch Para consultar um Message Batch, 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: ```bash cURL #!/bin/sh # ... # Verifique o status; repita até que processing_status seja "ended" curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ | jq -r '.processing_status' ``` ```bash CLI #!/bin/bash # ... # Verifique o status; repita até que processing_status seja "ended" ant messages:batches retrieve \ --message-batch-id "$MESSAGE_BATCH_ID" \ --transform processing_status --raw-output ``` ```python Python 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) ``` ```typescript TypeScript const client = new Anthropic(); const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"; let messageBatch; while (true) { messageBatch = await client.messages.batches.retrieve(messageBatchId); if (messageBatch.processing_status === "ended") { break; } console.log(`Batch ${messageBatchId} is still processing... waiting`); await new Promise((resolve) => setTimeout(resolve, 60_000)); } console.log(messageBatch); ``` ```csharp C# AnthropicClient client = new(); string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID"); MessageBatch messageBatch = null; while (true) { messageBatch = await client.Messages.Batches.Retrieve(messageBatchId); if (messageBatch.ProcessingStatus == "ended") { break; } Console.WriteLine($"Batch {messageBatchId} is still processing..."); await Task.Delay(60000); } Console.WriteLine(messageBatch); ``` ```go Go client := anthropic.NewClient() messageBatchID := os.Getenv("MESSAGE_BATCH_ID") var messageBatch *anthropic.MessageBatch for { var err error messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID, anthropic.MessageBatchGetParams{}) if err != nil { log.Fatal(err) } if messageBatch.ProcessingStatus == "ended" { break } fmt.Printf("Batch %s is still processing...\n", messageBatchID) time.Sleep(60 * time.Second) } fmt.Println(messageBatch) ``` ```java Java import com.anthropic.models.messages.batches.MessageBatch; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"; MessageBatch messageBatch = null; while (true) { messageBatch = client.messages().batches().retrieve(messageBatchId); if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) { break; } System.out.println("Batch " + messageBatchId + " is still processing..."); Thread.sleep(60000); } System.out.println(messageBatch); ``` ```php PHP $client = new Client(); $messageBatchId = getenv("MESSAGE_BATCH_ID"); $messageBatch = null; while (true) { $messageBatch = $client->messages->batches->retrieve( messageBatchID: $messageBatchId, ); if ($messageBatch->processingStatus === "ended") { break; } echo "Batch {$messageBatchId} is still processing...\n"; sleep(60); } echo json_encode($messageBatch, JSON_PRETTY_PRINT); ``` ```ruby Ruby client = Anthropic::Client.new message_batch_id = ENV["MESSAGE_BATCH_ID"] message_batch = nil loop do message_batch = client.messages.batches.retrieve(message_batch_id) break if message_batch.processing_status == :ended puts "Batch #{message_batch_id} is still processing..." sleep 60 end puts message_batch ``` ### Listando todos os Message Batches Você pode listar todos os Message Batches no seu Workspace usando o [endpoint de listagem](https://platform.claude.com/docs/pt-BR/api/messages/batches/list). A API suporta paginação, buscando automaticamente páginas adicionais conforme necessário: ```bash cURL #!/bin/sh # Busca uma página. Enquanto has_more da resposta for true, passe seu # last_id como after_id para buscar a próxima página. (Os SDKs e a CLI # realizam paginação automática.) curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" ``` ```bash CLI # Busca automaticamente mais páginas conforme necessário ant messages:batches list --limit 20 ``` ```python Python client = anthropic.Anthropic() # Busca automaticamente mais páginas conforme necessário. for message_batch in client.messages.batches.list(limit=20): print(message_batch) ``` ```typescript TypeScript const client = new Anthropic(); // Busca automaticamente mais páginas conforme necessário. for await (const messageBatch of client.messages.batches.list({ limit: 20 })) { console.log(messageBatch); } ``` ```csharp C# AnthropicClient client = new(); var parameters = new BatchListParams { Limit = 20 }; // Busca automaticamente mais páginas conforme necessário var page = await client.Messages.Batches.List(parameters); await foreach (var messageBatch in page.Paginate()) { Console.WriteLine(messageBatch); } ``` ```go Go client := anthropic.NewClient() // Busca automaticamente mais páginas conforme necessário iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{ Limit: anthropic.Int(20), }) for iter.Next() { messageBatch := iter.Current() fmt.Println(messageBatch) } if err := iter.Err(); err != nil { log.Fatal(err) } ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // Busca automaticamente mais páginas conforme necessário for (MessageBatch messageBatch : client .messages() .batches() .list(BatchListParams.builder().limit(20).build()) .autoPager()) { System.out.println(messageBatch); } ``` ```php PHP $client = new Client(); // Busca automaticamente mais páginas conforme necessário foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) { echo $messageBatch->id . "\n"; } ``` ```ruby Ruby client = Anthropic::Client.new # Busca automaticamente mais páginas conforme necessário client.messages.batches.list(limit: 20).auto_paging_each do |message_batch| puts message_batch end ``` ### Recuperando resultados do lote Quando o processamento do lote tiver terminado, cada requisição de Messages no lote terá um resultado. Existem quatro 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 erros possíveis 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 essa 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 essa requisição pudesse ser enviada ao modelo. Você não será cobrado por essas requisições. | O `request_counts` do lote mostra uma visão geral dos seus resultados, indicando quantas requisiçõ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 streaming dos resultados](https://platform.claude.com/docs/pt-BR/api/messages/batches/results) em vez de baixá-los todos de uma vez. ```bash cURL #!/bin/sh # Busque a results_url do lote e faça streaming dos resultados .jsonl # para os quais ela aponta. Para tratamento por resultado (retentativas, erros de validação), # use os exemplos do SDK nas outras abas. RESULTS_URL=$(curl -s "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \ --header "anthropic-version: 2023-06-01" \ --header "x-api-key: $ANTHROPIC_API_KEY" \ | jq -r '.results_url') curl -s "$RESULTS_URL" \ --header "anthropic-version: 2023-06-01" \ --header "x-api-key: $ANTHROPIC_API_KEY" \ | jq -r '"\(.result.type): \(.custom_id)"' ``` ```bash CLI # Imprime uma linha por resultado, ex.: `{"custom_id":"test-1","type":"succeeded",…}`. # Para tratamento por resultado (novas tentativas, erros de validação), use os exemplos # do SDK nas outras abas. ant messages:batches results \ --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \ --transform '{custom_id,"type":result.type,"error":result.error.error.type}' \ --format jsonl ``` ```python Python client = anthropic.Anthropic() # Faz streaming do arquivo de resultados em blocos eficientes em memória, processando um por vez for result in client.messages.batches.results( "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", ): outcome = result.result match outcome.type: case "succeeded": print(f"Success! {result.custom_id}") case "errored": if outcome.error.error.type == "invalid_request_error": # O corpo da requisição deve ser corrigido antes de reenviar a requisição print(f"Validation error {result.custom_id}") else: # A requisição pode ser repetida diretamente print(f"Server error {result.custom_id}") case "expired": print(f"Request expired {result.custom_id}") ``` ```typescript TypeScript const client = new Anthropic(); // Faz streaming do arquivo de resultados em blocos eficientes em memória, processando um de cada vez for await (const result of await client.messages.batches.results( "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" )) { switch (result.result.type) { case "succeeded": console.log(`Success! ${result.custom_id}`); break; case "errored": if (result.result.error.type === "invalid_request_error") { // O corpo da requisição deve ser corrigido antes de reenviar a requisição console.log(`Validation error: ${result.custom_id}`); } else { // A requisição pode ser repetida diretamente console.log(`Server error: ${result.custom_id}`); } break; case "expired": console.log(`Request expired: ${result.custom_id}`); break; } } ``` ```csharp C# AnthropicClient client = new(); await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")) { switch (result.Result.Type) { case "succeeded": Console.WriteLine($"Success! {result.CustomID}"); break; case "errored": if (result.Result.Error?.Type == "invalid_request") { Console.WriteLine($"Validation error: {result.CustomID}"); } else { Console.WriteLine($"Server error: {result.CustomID}"); } break; case "expired": Console.WriteLine($"Request expired: {result.CustomID}"); break; } } ``` ```go Go client := anthropic.NewClient() stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", anthropic.MessageBatchResultsParams{}) for stream.Next() { result := stream.Current() switch variant := result.Result.AsAny().(type) { case anthropic.MessageBatchSucceededResult: fmt.Printf("Success! %s\n", result.CustomID) case anthropic.MessageBatchErroredResult: fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message) case anthropic.MessageBatchExpiredResult: fmt.Printf("Request expired: %s\n", result.CustomID) } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.core.http.StreamResponse; import com.anthropic.models.messages.batches.BatchResultsParams; import com.anthropic.models.messages.batches.MessageBatchIndividualResponse; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // Faz streaming do arquivo de resultados em blocos eficientes em memória, processando um de cada vez try ( StreamResponse streamResponse = client .messages() .batches() .resultsStreaming( BatchResultsParams.builder() .messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d") .build() ) ) { streamResponse .stream() .forEach(result -> { switch (result.result().type().value()) { case SUCCEEDED -> System.out.println("Success! " + result.customId()); case ERRORED -> { if (result.result().asErrored().error().error().isInvalidRequestError()) { // O corpo da requisição deve ser corrigido antes de reenviar a requisição System.out.println("Validation error: " + result.customId()); } else { // A requisição pode ser repetida diretamente System.out.println("Server error: " + result.customId()); } } case EXPIRED -> System.out.println("Request expired: " + result.customId()); } }); } ``` ```php PHP use Anthropic\Messages\Batches\MessageBatchErroredResult; use Anthropic\Messages\Batches\MessageBatchExpiredResult; use Anthropic\Messages\Batches\MessageBatchSucceededResult; $client = new Client(); foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) { switch (true) { case $result->result instanceof MessageBatchSucceededResult: echo "Success! {$result->customID}\n"; break; case $result->result instanceof MessageBatchErroredResult: if ($result->result->error->error->type === "invalid_request_error") { echo "Validation error: {$result->customID}\n"; } else { echo "Server error: {$result->customID}\n"; } break; case $result->result instanceof MessageBatchExpiredResult: echo "Request expired: {$result->customID}\n"; break; } } ``` ```ruby Ruby client = Anthropic::Client.new client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result| outcome = result.result case outcome when Anthropic::Models::Messages::MessageBatchSucceededResult puts "Success! #{result.custom_id}" when Anthropic::Models::Messages::MessageBatchErroredResult if outcome.error.type == :invalid_request puts "Validation error: #{result.custom_id}" else puts "Server error: #{result.custom_id}" end when Anthropic::Models::Messages::MessageBatchExpiredResult puts "Request expired: #{result.custom_id}" end end ``` Os resultados estão no formato `.jsonl`, em que cada linha é um objeto JSON válido representando o resultado de uma única requisição no Message Batch. Para cada resultado transmitido via streaming, você pode fazer algo diferente dependendo do seu `custom_id` e do tipo de resultado. Aqui está um exemplo de conjunto de resultados: ```jsonl .jsonl file {"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","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-5-5","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](https://platform.claude.com/docs/pt-BR/api/errors#error-shapes) 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 anterior, o resultado da segunda requisição do lote é retornado antes da primeira. Para corresponder corretamente os resultados às suas requisições correspondentes, sempre use o campo `custom_id`. ### Cancelando um Message Batch Você pode cancelar um Message Batch que está sendo processado usando o [endpoint de cancelamento](https://platform.claude.com/docs/pt-BR/api/messages/batches/cancel). Imediatamente após o cancelamento, o `processing_status` de um lote será `canceling`. Você pode usar a mesma técnica de polling descrita anteriormente para aguardar até que o cancelamento seja finalizado. Os lotes cancelados terminam com um status `ended` e podem conter resultados parciais para requisições que foram processadas antes do cancelamento. ```bash cURL #!/bin/sh # ... curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" ``` ```bash CLI #!/bin/bash # ... ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID" ``` ```python Python client = anthropic.Anthropic() MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" message_batch = client.messages.batches.cancel( MESSAGE_BATCH_ID, ) print(message_batch) ``` ```typescript TypeScript const client = new Anthropic(); const messageBatch = await client.messages.batches.cancel(MESSAGE_BATCH_ID); console.log(messageBatch); ``` ```csharp C# AnthropicClient client = new(); string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID"); var messageBatch = await client.Messages.Batches.Cancel(messageBatchId); Console.WriteLine(messageBatch); ``` ```go Go client := anthropic.NewClient() messageBatchID := os.Getenv("MESSAGE_BATCH_ID") messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID, anthropic.MessageBatchCancelParams{}) if err != nil { log.Fatal(err) } fmt.Println(messageBatch) ``` ```java Java import com.anthropic.models.messages.batches.*; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageBatch messageBatch = client .messages() .batches() .cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"); System.out.println(messageBatch); ``` ```php PHP $client = new Client(); $messageBatch = $client->messages->batches->cancel( messageBatchID: 'msgbatch_example_id', ); echo $messageBatch; ``` ```ruby Ruby client = Anthropic::Client.new message_batch_id = ENV.fetch("MESSAGE_BATCH_ID") message_batch = client.messages.batches.cancel(message_batch_id) puts message_batch ``` A resposta mostra o lote em um estado `canceling`: ```json Output { "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 Message Batches API suporta "prompt caching" (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 ser acumulados, 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 que variam 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: 1. Inclua blocos `cache_control` idênticos em cada requisição de Message dentro do seu lote. 2. Mantenha um fluxo constante de requisições para evitar que as entradas de cache expirem após seu tempo de vida de 5 minutos. 3. Estruture suas requisições para compartilhar o máximo possível de conteúdo em cache. Exemplo de implementação de cache de prompt em um lote: ```bash cURL 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-5-5", "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": "", "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-5-5", "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": "", "cache_control": {"type": "ephemeral"} } ], "messages": [ {"role": "user", "content": "Write a summary of Pride and Prejudice."} ] } } ] }' ``` ```bash CLI ant messages:batches create <<'YAML' requests: - custom_id: my-first-request params: model: claude-opus-5-5 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. - type: text text: "" 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-5-5 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. - type: text text: "" cache_control: type: ephemeral messages: - role: user content: Write a summary of Pride and Prejudice. YAML ``` ```python Python 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-5-5", 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": "", "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-5-5", 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": "", "cache_control": {"type": "ephemeral"}, }, ], messages=[ { "role": "user", "content": "Write a summary of Pride and Prejudice.", } ], ), ), ] ) ``` ```typescript TypeScript const client = new Anthropic(); const messageBatch = await client.messages.batches.create({ requests: [ { custom_id: "my-first-request", params: { model: "claude-opus-5-5", 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: "", 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-5-5", 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: "", cache_control: { type: "ephemeral" } } ], messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }] } } ] }); ``` ```csharp C# using Anthropic; using Anthropic.Models.Messages; using Anthropic.Models.Messages.Batches; AnthropicClient client = new() { ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") }; var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams { Requests = [ new() { CustomID = "my-first-request", Params = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, System = new List { new() { 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" }, new() { Text = "", CacheControl = new() } }, Messages = [ new() { Role = Role.User, Content = "Analyze the major themes in Pride and Prejudice." } ] } }, new() { CustomID = "my-second-request", Params = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, System = new List { new() { 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" }, new() { Text = "", CacheControl = new() } }, Messages = [ new() { Role = Role.User, Content = "Write a summary of Pride and Prejudice." } ] } } ] }); ``` ```go Go client := anthropic.NewClient() messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{ Requests: []anthropic.MessageBatchNewParamsRequest{ { CustomID: "my-first-request", Params: anthropic.MessageBatchNewParamsRequestParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, System: []anthropic.TextBlockParam{ { 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", }, { Text: "", CacheControl: anthropic.NewCacheControlEphemeralParam(), }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")), }, }, }, { CustomID: "my-second-request", Params: anthropic.MessageBatchNewParamsRequestParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, System: []anthropic.TextBlockParam{ { 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", }, { Text: "", CacheControl: anthropic.NewCacheControlEphemeralParam(), }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")), }, }, }, }, }) if err != nil { log.Fatal(err) } fmt.Println(messageBatch) ``` ```java Java import com.anthropic.models.messages.CacheControlEphemeral; // ... import com.anthropic.models.messages.batches.*; // ... AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BatchCreateParams createParams = BatchCreateParams.builder() .addRequest( BatchCreateParams.Request.builder() .customId("my-first-request") .params( BatchCreateParams.Request.Params.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .systemOfTextBlockParams( List.of( TextBlockParam.builder() .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" ) .build(), TextBlockParam.builder() .text("") .cacheControl(CacheControlEphemeral.builder().build()) .build() ) ) .addUserMessage("Analyze the major themes in Pride and Prejudice.") .build() ) .build() ) .addRequest( BatchCreateParams.Request.builder() .customId("my-second-request") .params( BatchCreateParams.Request.Params.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .systemOfTextBlockParams( List.of( TextBlockParam.builder() .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" ) .build(), TextBlockParam.builder() .text("") .cacheControl(CacheControlEphemeral.builder().build()) .build() ) ) .addUserMessage("Write a summary of Pride and Prejudice.") .build() ) .build() ) .build(); MessageBatch messageBatch = client.messages().batches().create(createParams); ``` ```php PHP $client = new Client(); $messageBatch = $client->messages->batches->create( requests: [ [ 'custom_id' => 'my-first-request', 'params' => [ 'model' => 'claude-opus-5-5', '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' => '', '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-5-5', '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' => '', 'cache_control' => ['type' => 'ephemeral'] ] ], 'messages' => [ ['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.'] ] ] ] ], ); ``` ```ruby Ruby client = Anthropic::Client.new message_batch = client.messages.batches.create( requests: [ { custom_id: "my-first-request", params: { model: "claude-opus-5-5", 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: "", 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-5-5", 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: "", cache_control: { type: "ephemeral" } } ], messages: [ { role: "user", content: "Write a summary of Pride and Prejudice." } ] } } ] ) ``` Neste exemplo, ambas as requisições no lote incluem mensagens de sistema idênticas e o texto completo de Orgulho e Preconceito marcado com `cache_control` para aumentar a probabilidade de acertos de cache. ### Ferramentas de servidor e o loop agêntico Todas as [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) (busca na web, busca de conteúdo web, execução de código, conectores MCP, advisor e busca de ferramentas) funcionam em requisições em lote. O worker de lote executa o mesmo loop agêntico do lado do servidor que a Messages API síncrona. Como não há conexão aberta para manter, o loop de lote executa **mais iterações por turno** do que uma requisição síncrona antes de retornar `stop_reason: "pause_turn"`. Se um resultado de lote retornar com `pause_turn`, o turno não terminou; você pode continuá-lo enviando o conteúdo pausado do assistente em uma requisição subsequente (em lote ou síncrona) exatamente como mostrado no [padrão de continuação de pause\_turn](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). O worker de lote adicionalmente limita `web_search` por organização para que o processamento em lote altamente concorrente não esgote o limite de taxa de busca na web da sua organização. O lote tenta novamente as requisições limitadas automaticamente; você não precisa lidar com isso por conta própria, mas lotes muito grandes de busca na web podem levar mais tempo para serem concluídos. ### Saída estendida (beta) O cabeçalho beta `output-300k-2026-03-24` eleva o limite de `max_tokens` para 300.000 em solicitações em lote usando Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 ou Claude Haiku 5.5. Inclua o cabeçalho para gerar saídas muito mais longas do que o limite padrão de 128k de `max_tokens` em um único turno. A saída estendida está disponível apenas na Message Batches API, não na Messages API síncrona. Ela é suportada na Claude API e na Claude Platform na AWS, e atualmente não está disponível no Amazon Bedrock, Google Cloud ou Microsoft Foundry. Use a saída estendida para geração de conteúdo longo, como rascunhos com extensão de livro e documentação técnica, extração exaustiva de dados estruturados, grandes estruturas de geração de código e longas cadeias de raciocínio. Uma única geração de 300k tokens pode levar mais de uma hora para ser concluída, portanto planeje seus envios de lote tendo em mente a janela de processamento de 24 horas. Aplica-se o preço padrão de lote (50% dos preços padrão da API). ```bash cURL curl https://api.anthropic.com/v1/messages/batches \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: output-300k-2026-03-24" \ --header "content-type: application/json" \ --data \ '{ "requests": [ { "custom_id": "long-form-request", "params": { "model": "claude-opus-5-5", "max_tokens": 300000, "messages": [ {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."} ] } } ] }' ``` ```bash CLI ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML' requests: - custom_id: long-form-request params: model: claude-opus-5-5 max_tokens: 300000 messages: - role: user content: >- Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices. YAML ``` ```python Python 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-5-5", 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) ``` ```typescript TypeScript const client = new Anthropic(); const messageBatch = await client.beta.messages.batches.create({ betas: ["output-300k-2026-03-24"], requests: [ { custom_id: "long-form-request", params: { model: "claude-opus-5-5", max_tokens: 300000, messages: [ { role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." } ] } } ] }); console.log(messageBatch); ``` ```csharp C# using Anthropic; using Anthropic.Models.Beta.Messages; using Anthropic.Models.Beta.Messages.Batches; using Model = Anthropic.Models.Messages.Model; AnthropicClient client = new(); var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams { Betas = ["output-300k-2026-03-24"], Requests = [ new() { CustomID = "long-form-request", Params = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 300_000, Messages = [ new() { Role = Role.User, Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." } ] } } ] }); Console.WriteLine(batch); ``` ```go Go client := anthropic.NewClient() batch, err := client.Beta.Messages.Batches.New(context.Background(), anthropic.BetaMessageBatchNewParams{ Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"}, Requests: []anthropic.BetaMessageBatchNewParamsRequest{ { CustomID: "long-form-request", Params: anthropic.BetaMessageBatchNewParamsRequestParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 300_000, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage( anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."), ), }, }, }, }, }) if err != nil { panic(err) } fmt.Println(batch.ID) ``` ```java Java import com.anthropic.models.beta.messages.batches.*; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BatchCreateParams params = BatchCreateParams.builder() .addBeta("output-300k-2026-03-24") .addRequest( BatchCreateParams.Request.builder() .customId("long-form-request") .params( BatchCreateParams.Request.Params.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(300_000L) .addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.") .build() ) .build() ) .build(); BetaMessageBatch messageBatch = client.beta().messages().batches().create(params); IO.println(messageBatch); } ``` ```php PHP $client = new Client(); $batch = $client->beta->messages->batches->create( betas: ['output-300k-2026-03-24'], requests: [ [ 'custom_id' => 'long-form-request', 'params' => [ 'model' => 'claude-opus-5-5', '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.'] ] ] ] ], ); echo $batch->id; ``` ```ruby Ruby client = Anthropic::Client.new batch = client.beta.messages.batches.create( betas: ["output-300k-2026-03-24"], requests: [ { custom_id: "long-form-request", params: { model: "claude-opus-5-5", 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." } ] } } ] ) puts batch ``` ### Melhores práticas para processamento em lote eficaz Para aproveitar ao máximo a Batches API: * Monitore o status de processamento do lote regularmente e implemente lógica de repetição apropriada para requisições com falha. * Use valores de `custom_id` significativos para corresponder facilmente os resultados às requisições, já que a ordem não é garantida. * Considere dividir conjuntos de dados muito grandes em vários lotes para melhor gerenciamento. * Faça um teste com um único formato de requisição na Messages API para evitar erros de validação. ### Solução de problemas comuns Se estiver enfrentando comportamento inesperado: * Verifique se o tamanho total da requisição do 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](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#supported-models) para todas as requisições no lote. * Garanta que cada requisição no lote tenha um `custom_id` único. * Garanta que tenham passado menos de 29 dias desde o horário `created_at` do lote (não o horário `ended_at` do processamento). Se mais de 29 dias tiverem passado, os resultados não poderão mais ser visualizados. * Confirme que o lote não foi cancelado. Observe que a falha de uma requisição em um lote não afeta o processamento das outras requisições. ## Armazenamento e privacidade de lotes * **Isolamento de Workspace**: os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por requisições de API nesse mesmo 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}`. Para excluir um lote em andamento, cancele-o primeiro. O processamento assíncrono requer armazenamento do lado do servidor tanto das entradas quanto das 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](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention). ## Perguntas frequentes Os lotes podem levar até 24 horas para serem processados, mas muitos terminam antes. O tempo real de processamento depende do tamanho do lote, da demanda atual e do seu volume de requisições. É possível que um lote expire e não seja concluído em 24 horas. Consulte [Modelos suportados](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#supported-models) para a lista de modelos suportados. Sim, a Message Batches API suporta quase todos os recursos disponíveis na Messages API, incluindo a maioria dos recursos beta. Um pequeno número de parâmetros (`stream`, `speed` e `max_tokens: 0`) não é suportado. Consulte [O que pode ser processado em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#what-can-be-batched) para ver a lista completa. A Message Batches API oferece um desconto de 50% em todo o uso em comparação com os preços padrão da API. Isso se aplica a tokens de entrada, tokens de saída e quaisquer tokens especiais. Para mais informações sobre preços, visite [Preços](https://claude.com/pricing#anthropic-api). Não, uma vez que um lote foi enviado, ele não pode ser modificado. Se você precisar fazer alterações, deve cancelar o lote atual e enviar um novo. Observe que o cancelamento pode não ter efeito imediato. A Message Batches API tem limites de taxa baseados em requisições HTTP, além de limites no número de requisições que precisam de processamento. Consulte [limites de taxa da Message Batches API](https://platform.claude.com/docs/pt-BR/api/rate-limits#message-batches-api). O uso da Batches API não afeta os limites de taxa na Messages API. Quando você recupera os resultados, cada requisição tem um campo `result` indicando se ela `succeeded`, `errored`, foi `canceled` ou `expired`. Para resultados `errored`, informações adicionais de erro são fornecidas. Veja o objeto de resposta de erro na [referência da API](https://platform.claude.com/docs/pt-BR/api/messages/batches/create). A Message Batches API foi projetada com fortes medidas de privacidade e separação de dados: 1. Os lotes e seus resultados são isolados dentro do Workspace em que foram criados. Isso significa que eles só podem ser acessados por requisições de API nesse mesmo Workspace. 2. Cada requisição dentro de um lote é processada de forma independente, sem vazamento de dados entre requisições. 3. Os resultados ficam disponíveis apenas por um tempo limitado (29 dias) e seguem a [política de retenção de dados](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) da Anthropic. 4. O download de resultados de lote no Console pode ser desativado no nível da organização ou por workspace. Sim, é possível usar cache de prompt com a Message Batches API. No entanto, como as requisições em lote assíncronas podem ser processadas de forma concorrente e em qualquer ordem, os acertos de cache são fornecidos com base no melhor esforço. ## Próximos passos Habilite citações naturais para aplicações RAG fornecendo resultados de busca com atribuição de fonte. Reduza custo e latência armazenando em cache prefixos de prompt compartilhados entre requisições em um lote.