L’elaborazione batch è un approccio potente per gestire grandi volumi di richieste in modo efficiente. Invece di elaborare le richieste una alla volta con risposte immediate, l’elaborazione batch ti consente di inviare più richieste insieme per l’elaborazione asincrona. Questo pattern è particolarmente utile quando:
  • Devi elaborare grandi volumi di dati
  • Non sono richieste risposte immediate
  • Vuoi ottimizzare per l’efficienza dei costi
  • Stai eseguendo valutazioni o analisi su larga scala
L’API Message Batches è la nostra prima implementazione di questo pattern.

​
API Message Batches

L’API Message Batches è un modo potente ed economico per elaborare in modo asincrono grandi volumi di richieste Messages. Questo approccio è adatto per attività che non richiedono risposte immediate, con la maggior parte dei batch che si completa in meno di 1 ora riducendo i costi del 50% e aumentando il throughput. Puoi esplorare il riferimento API direttamente, oltre a questa guida.

​
Come funziona l’API Message Batches

Quando invii una richiesta all’API Message Batches:
  1. Il sistema crea un nuovo Message Batch con le richieste Messages fornite.
  2. Il batch viene quindi elaborato in modo asincrono, con ogni richiesta gestita indipendentemente.
  3. Puoi fare polling per lo stato del batch e recuperare i risultati quando l’elaborazione è terminata per tutte le richieste.
Questo è particolarmente utile per operazioni bulk che non richiedono risultati immediati, come:
  • Valutazioni su larga scala: Elabora migliaia di casi di test in modo efficiente.
  • Moderazione dei contenuti: Analizza grandi volumi di contenuti generati dagli utenti in modo asincrono.
  • Analisi dei dati: Genera insights o riassunti per grandi dataset.
  • Generazione di contenuti bulk: Crea grandi quantità di testo per vari scopi (ad esempio, descrizioni di prodotti, riassunti di articoli).

​
Limitazioni dei batch

  • Un Message Batch è limitato a 100.000 richieste Message o 256 MB di dimensione, qualunque sia raggiunto per primo.
  • Elaboriamo ogni batch il più velocemente possibile, con la maggior parte dei batch che si completa entro 1 ora. Sarai in grado di accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, qualunque arrivi prima. I batch scadranno se l’elaborazione non si completa entro 24 ore.
  • I risultati del batch sono disponibili per 29 giorni dopo la creazione. Dopo di che, puoi ancora visualizzare il Batch, ma i suoi risultati non saranno più disponibili per il download.
  • I batch sono limitati a un Workspace. Puoi visualizzare tutti i batch—e i loro risultati—che sono stati creati all’interno del Workspace a cui appartiene la tua chiave API.
  • I limiti di velocità si applicano sia alle richieste HTTP dell’API Batches che al numero di richieste all’interno di un batch in attesa di essere elaborate. Vedi Limiti di velocità dell’API Message Batches. Inoltre, potremmo rallentare l’elaborazione in base alla domanda attuale e al tuo volume di richieste. In tal caso, potresti vedere più richieste scadere dopo 24 ore.
  • A causa dell’alto throughput e dell’elaborazione concorrente, i batch potrebbero superare leggermente il limite di spesa configurato del tuo Workspace.

​
Modelli supportati

Tutti i modelli attivi supportano l’API Message Batches.

​
Cosa può essere elaborato in batch

Qualsiasi richiesta che puoi fare all’API Messages può essere inclusa in un batch. Questo include:
  • Vision
  • Uso di strumenti
  • Messaggi di sistema
  • Conversazioni multi-turno
  • Qualsiasi funzionalità beta
Poiché ogni richiesta nel batch viene elaborata indipendentemente, puoi mescolare diversi tipi di richieste all’interno di un singolo batch.
Poiché i batch possono richiedere più di 5 minuti per essere elaborati, considera di utilizzare la durata della cache di 1 ora con il prompt caching per migliori tassi di hit della cache quando elabori batch con contesto condiviso.

​
Prezzi

L’API Batches offre significativi risparmi sui costi. Tutto l’utilizzo viene addebitato al 50% dei prezzi API standard.
ModelBatch inputBatch 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 (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

​
Come utilizzare l’API Message Batches

​
Prepara e crea il tuo batch

Un Message Batch è composto da un elenco di richieste per creare un Message. La forma di una singola richiesta è composta da:
  • Un custom_id unico per identificare la richiesta Messages
  • Un oggetto params con i parametri standard dell’API Messages
Puoi creare un batch passando questo elenco nel parametro 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-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'
In questo esempio, due richieste separate vengono raggruppate insieme per l’elaborazione asincrona. Ogni richiesta ha un custom_id unico e contiene i parametri standard che useresti per una chiamata all’API Messages.
Testa le tue richieste batch con l’API MessagesLa validazione dell’oggetto params per ogni richiesta di messaggio viene eseguita in modo asincrono, e gli errori di validazione vengono restituiti quando l’elaborazione dell’intero batch è terminata. Puoi assicurarti di costruire correttamente il tuo input verificando prima la forma della tua richiesta con l’API Messages.
Quando un batch viene creato per la prima volta, la risposta avrà uno stato di elaborazione di 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
}

​
Tracciamento del tuo batch

Il campo processing_status del Message Batch indica la fase di elaborazione in cui si trova il batch. Inizia come in_progress, poi si aggiorna a ended una volta che tutte le richieste nel batch hanno finito l’elaborazione, e i risultati sono pronti. Puoi monitorare lo stato del tuo batch visitando la Console, o utilizzando l’endpoint di recupero: 
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/'
Puoi fare polling di questo endpoint per sapere quando l’elaborazione è terminata.

​
Recupero dei risultati del batch

Una volta che l’elaborazione del batch è terminata, ogni richiesta Messages nel batch avrà un risultato. Ci sono 4 tipi di risultato:
Tipo di RisultatoDescrizione
succeededLa richiesta è stata completata con successo. Include il risultato del messaggio.
erroredLa richiesta ha riscontrato un errore e un messaggio non è stato creato. Gli errori possibili includono richieste non valide e errori interni del server. Non ti verrà addebitato per queste richieste.
canceledL’utente ha cancellato il batch prima che questa richiesta potesse essere inviata al modello. Non ti verrà addebitato per queste richieste.
expiredIl batch ha raggiunto la sua scadenza di 24 ore prima che questa richiesta potesse essere inviata al modello. Non ti verrà addebitato per queste richieste.
Vedrai una panoramica dei tuoi risultati con i request_counts del batch, che mostra quante richieste hanno raggiunto ciascuno di questi quattro stati. I risultati del batch sono disponibili per il download nella proprietà results_url del Message Batch, e se il permesso dell’organizzazione lo consente, nella Console. A causa della dimensione potenzialmente grande dei risultati, è raccomandato fare streaming dei risultati piuttosto che scaricarli tutti in una volta. 
#!/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
I risultati saranno in formato .jsonl, dove ogni riga è un oggetto JSON valido che rappresenta il risultato di una singola richiesta nel Message Batch. Per ogni risultato in streaming, puoi fare qualcosa di diverso a seconda del suo custom_id e tipo di risultato. Ecco un esempio di set di risultati:
.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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 il tuo risultato ha un errore, il suo result.error sarà impostato sulla nostra forma di errore standard.
I risultati del batch potrebbero non corrispondere all’ordine di inputI risultati del batch possono essere restituiti in qualsiasi ordine, e potrebbero non corrispondere all’ordinamento delle richieste quando il batch è stato creato. Nell’esempio sopra, il risultato per la seconda richiesta del batch viene restituito prima della prima. Per abbinare correttamente i risultati con le loro richieste corrispondenti, usa sempre il campo custom_id.

​
Utilizzo del prompt caching con Message Batches

L’API Message Batches supporta il prompt caching, permettendoti di ridurre potenzialmente i costi e i tempi di elaborazione per le richieste batch. Gli sconti sui prezzi dal prompt caching e dai Message Batches possono accumularsi, fornendo risparmi sui costi ancora maggiori quando entrambe le funzionalità vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e concorrente, gli hit della cache vengono forniti su base best-effort. Gli utenti tipicamente sperimentano tassi di hit della cache che vanno dal 30% al 98%, a seconda dei loro pattern di traffico. Per massimizzare la probabilità di hit della cache nelle tue richieste batch:
  1. Includi blocchi cache_control identici in ogni richiesta Message all’interno del tuo batch
  2. Mantieni un flusso costante di richieste per prevenire che le voci della cache scadano dopo la loro durata di vita di 5 minuti
  3. Struttura le tue richieste per condividere il più possibile contenuto cached
Esempio di implementazione del prompt caching in un batch: 
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-sonnet-4-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": "<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-sonnet-4-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": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'
In questo esempio, entrambe le richieste nel batch includono messaggi di sistema identici e il testo completo di Pride and Prejudice contrassegnato con cache_control per aumentare la probabilità di hit della cache.

​
Best practice per un batching efficace

Per ottenere il massimo dall’API Batches:
  • Monitora regolarmente lo stato di elaborazione del batch e implementa una logica di retry appropriata per le richieste fallite.
  • Usa valori custom_id significativi per abbinare facilmente i risultati con le richieste, poiché l’ordine non è garantito.
  • Considera di suddividere dataset molto grandi in più batch per una migliore gestibilità.
  • Esegui un test a secco di una singola forma di richiesta con l’API Messages per evitare errori di validazione.

​
Risoluzione dei problemi comuni

Se stai sperimentando comportamenti inaspettati:
  • Verifica che la dimensione totale della richiesta batch non superi i 256 MB. Se la dimensione della richiesta è troppo grande, potresti ottenere un errore 413 request_too_large.
  • Controlla che stai utilizzando modelli supportati per tutte le richieste nel batch.
  • Assicurati che ogni richiesta nel batch abbia un custom_id unico.
  • Assicurati che siano passati meno di 29 giorni dal tempo created_at del batch (non dal tempo ended_at dell’elaborazione). Se sono passati più di 29 giorni, i risultati non saranno più visualizzabili.
  • Conferma che il batch non sia stato cancellato.
Nota che il fallimento di una richiesta in un batch non influisce sull’elaborazione delle altre richieste.

​
Archiviazione e privacy dei batch

  • Isolamento del workspace: I batch sono isolati all’interno del Workspace in cui sono creati. Possono essere accessibili solo dalle chiavi API associate a quel Workspace, o dagli utenti con permesso di visualizzare i batch del Workspace nella Console.
  • Disponibilità dei risultati: I risultati del batch sono disponibili per 29 giorni dopo la creazione del batch, consentendo ampio tempo per il recupero e l’elaborazione.

​
FAQ

I batch possono richiedere fino a 24 ore per l’elaborazione, ma molti finiranno prima. Il tempo di elaborazione effettivo dipende dalla dimensione del batch, dalla domanda attuale e dal tuo volume di richieste. È possibile che un batch scada e non si completi entro 24 ore.
Vedi sopra per l’elenco dei modelli supportati.
Sì, l’API Message Batches supporta tutte le funzionalità disponibili nell’API Messages, incluse le funzionalità beta. Tuttavia, lo streaming non è supportato per le richieste batch.
L’API Message Batches offre uno sconto del 50% su tutto l’utilizzo rispetto ai prezzi API standard. Questo si applica ai token di input, ai token di output e a qualsiasi token speciale. Per maggiori informazioni sui prezzi, visita la nostra pagina dei prezzi.
No, una volta che un batch è stato inviato, non può essere modificato. Se devi apportare modifiche, dovresti cancellare il batch corrente e inviarne uno nuovo. Nota che la cancellazione potrebbe non avere effetto immediato.
L’API Message Batches ha limiti di velocità basati sulle richieste HTTP oltre ai limiti sul numero di richieste che necessitano di elaborazione. Vedi Limiti di velocità dell’API Message Batches. L’utilizzo dell’API Batches non influisce sui limiti di velocità nell’API Messages.
Quando recuperi i risultati, ogni richiesta avrà un campo result che indica se è succeeded, errored, è stata canceled, o è expired. Per i risultati errored, verranno fornite informazioni aggiuntive sull’errore. Visualizza l’oggetto di risposta dell’errore nel riferimento API.
L’API Message Batches è progettata con forti misure di privacy e separazione dei dati:
  1. I batch e i loro risultati sono isolati all’interno del Workspace in cui sono stati creati. Questo significa che possono essere accessibili solo dalle chiavi API dello stesso Workspace.
  2. Ogni richiesta all’interno di un batch viene elaborata indipendentemente, senza perdite di dati tra le richieste.
  3. I risultati sono disponibili solo per un tempo limitato (29 giorni), e seguono la nostra politica di conservazione dei dati.
  4. Il download dei risultati del batch nella Console può essere disabilitato a livello di organizzazione o per singolo workspace.
Sì, è possibile utilizzare il prompt caching con l’API Message Batches. Tuttavia, poiché le richieste batch asincrone possono essere elaborate contemporaneamente e in qualsiasi ordine, gli hit della cache vengono forniti su base best-effort.