- Você precisa processar grandes volumes de dados
- Respostas imediatas não são necessárias
- Você quer otimizar para eficiência de custo
- Você está executando avaliações ou análises em larga escala
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:- O sistema cria um novo Message Batch com as solicitações Messages fornecidas.
- O lote é então processado assincronamente, com cada solicitação tratada independentemente.
- Você pode consultar o status do lote e recuperar resultados quando o processamento terminar para todas as solicitações.
- Avaliações em larga escala: Processe milhares de casos de teste de forma eficiente.
- Moderação de conteúdo: Analise grandes volumes de conteúdo gerado pelo usuário 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 de 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
Todos os modelos ativos suportam a API Message Batches.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
- Quaisquer recursos beta
Como os lotes podem levar mais de 5 minutos para processar, 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 Batches oferece economias significativas de custo. Todo o uso é cobrado a 50% dos preços padrão da API.| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.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 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.5 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
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
paramscom os parâmetros padrão da API Messages
requests:
custom_id único e contém os parâmetros padrão que você usaria para uma chamada da API Messages.
Teste suas solicitações de lote com a API MessagesA validação do objeto
params para cada solicitação de mensagem é realizada assincronamente, e 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 a forma da sua solicitação com a API Messages primeiro.in_progress.
JSON
Rastreando seu lote
O campoprocessing_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:
Recuperando resultados do lote
Uma vez que o processamento do lote terminou, cada solicitação Messages no lote terá um resultado. Existem 4 tipos de resultado:| Tipo de Resultado | Descrição |
|---|---|
succeeded | Solicitação foi bem-sucedida. Inclui o resultado da mensagem. |
errored | Solicitação encontrou um erro e uma mensagem não foi criada. Possíveis erros incluem solicitações inválidas e erros internos do servidor. Você não será cobrado por essas solicitações. |
canceled | Usuário cancelou o lote antes que esta solicitação pudesse ser enviada para o modelo. Você não será cobrado por essas solicitações. |
expired | Lote atingiu sua expiração de 24 horas antes que esta solicitação pudesse ser enviada para o modelo. Você não será cobrado por essas solicitações. |
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 transmitir resultados de volta em vez de baixá-los todos de uma vez.
.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:
.jsonl file
result.error será definido para nossa forma de erro padrão.
Resultados de lote podem não corresponder à ordem de entradaOs resultados do lote podem ser retornados em qualquer ordem, e podem não corresponder à ordenação das solicitações quando o lote foi criado. No exemplo acima, o resultado para a segunda solicitação do lote é retornado antes da primeira. Para corresponder corretamente os resultados com suas solicitações correspondentes, sempre use o campo
custom_id.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 custo 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:- Inclua blocos
cache_controlidênticos em cada solicitação Message dentro do seu lote - Mantenha um fluxo constante de solicitações para evitar que entradas de cache expirem após seu tempo de vida de 5 minutos
- Estruture suas solicitações para compartilhar o máximo de conteúdo em cache possível
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 repetição apropriada para solicitações falhadas.
- Use valores
custom_idsignificativos para facilmente corresponder resultados com solicitações, já que a ordem não é garantida. - Considere dividir 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.
- Certifique-se de que cada solicitação no lote tem um
custom_idúnico. - Certifique-se de que passaram menos de 29 dias desde o tempo
created_atdo lote (não o tempoended_atdo processamento). Se mais de 29 dias se passaram, os resultados não estarão mais visíveis. - Confirme que o lote não foi cancelado.
Armazenamento e privacidade de lote
- Isolamento de 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
Quanto tempo leva para um lote processar?
Quanto tempo leva para um lote processar?
Os lotes podem levar até 24 horas para processamento, mas muitos terminarão mais cedo. O tempo real de processamento depende do tamanho do lote, demanda atual e volume de suas solicitações. É possível que um lote expire e não complete dentro de 24 horas.
A API Batches está disponível para todos os modelos?
A API Batches está disponível para todos os modelos?
Veja acima para a lista de modelos suportados.
Posso usar a API Message Batches com outros recursos da API?
Posso usar a API Message Batches com outros recursos da API?
Sim, a API Message Batches suporta todos os recursos disponíveis na API Messages, incluindo recursos beta. No entanto, streaming não é suportado para solicitações de lote.
Como a API Message Batches afeta os preços?
Como a API Message Batches afeta os preços?
A API Message Batches oferece um desconto de 50% em todo o uso comparado aos preços padrão da API. Isso se aplica a tokens de entrada, tokens de saída e quaisquer tokens especiais. Para mais sobre preços, visite nossa página de preços.
Posso atualizar um lote depois que foi enviado?
Posso atualizar um lote depois que foi enviado?
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. Note que o cancelamento pode não ter efeito imediato.
Existem limites de taxa da API Message Batches e eles interagem com os limites de taxa da API Messages?
Existem limites de taxa da API Message Batches e eles interagem com os limites de taxa da API Messages?
A API Message Batches tem limites de taxa baseados em solicitações HTTP além de limites no número de solicitações que precisam de processamento. Veja limites de taxa da API Message Batches. O uso da API Batches não afeta os limites de taxa na API Messages.
Como lidar com erros nas minhas solicitações de lote?
Como lidar com erros nas minhas solicitações de lote?
Quando você recuperar os resultados, cada solicitação terá um campo
result indicando se ela succeeded, errored, foi canceled, ou expired. Para resultados errored, informações adicionais de erro serão fornecidas. Veja o objeto de resposta de erro na referência da API.Como a API Message Batches lida com privacidade e separação de dados?
Como a API Message Batches lida com privacidade e separação de dados?
A API Message Batches é projetada com medidas fortes de privacidade e separação de dados:
- Os lotes e seus resultados são isolados dentro do Workspace em que foram criados. Isso significa que eles só podem ser acessados por chaves API do mesmo Workspace.
- Cada solicitação dentro de um lote é processada independentemente, sem vazamento de dados entre solicitações.
- Os resultados estão disponíveis apenas por um tempo limitado (29 dias), e seguem nossa política de retenção de dados.
- O download de resultados de lote no Console pode ser desabilitado no nível da organização ou por workspace.
Posso usar cache de prompt na API Message Batches?
Posso usar cache de prompt na API Message Batches?
Sim, é possível usar cache de prompt com a API Message Batches. No entanto, como as solicitações de lote assíncronas podem ser processadas concorrentemente e em qualquer ordem, os acertos de cache são fornecidos com base no melhor esforço.