L'elaborazione batch ("batch processing") è 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 necessarie risposte immediate
• Vuoi ottimizzare l'efficienza dei costi
• Stai eseguendo valutazioni o analisi su larga scala

La Message Batches API è la prima implementazione di questo pattern da parte di Anthropic.

Message Batches API

La Message Batches API è un modo potente ed economico per elaborare in modo asincrono grandi volumi di richieste Messages. Questo approccio è adatto ad attività che non richiedono risposte immediate: la maggior parte dei batch termina in meno di 1 ora, riducendo i costi del 50% e aumentando il throughput.

Puoi esplorare direttamente il riferimento API, oltre a questa guida.

Come funziona la Message Batches API

Quando invii una richiesta alla Message Batches API:

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 in modo indipendente.
3. Puoi interrogare lo stato del batch e recuperare i risultati quando l'elaborazione è terminata per tutte le richieste.

Questo è particolarmente utile per operazioni in blocco 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 approfondimenti o riepiloghi per grandi dataset.
• Generazione di contenuti in blocco: crea grandi quantità di testo per vari scopi (ad esempio, descrizioni di prodotti, riepiloghi di articoli).

Limitazioni dei batch

• Un Message Batch è limitato a 100.000 richieste Message oppure a 256 MB di dimensione, a seconda di quale limite viene raggiunto per primo.
• Il sistema elabora ogni batch il più velocemente possibile, con la maggior parte dei batch completati entro 1 ora. Puoi accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, a seconda di quale condizione si verifica per prima. I batch scadono se l'elaborazione non viene completata entro 24 ore.
• I risultati dei batch sono disponibili per 29 giorni dopo la creazione. Dopo tale periodo, puoi ancora visualizzare il Batch, ma i suoi risultati non saranno più disponibili per il download.
• I batch sono limitati all'ambito di un Workspace. Puoi visualizzare tutti i batch (e i relativi risultati) creati all'interno del Workspace in cui viene eseguita la tua richiesta.
• I "rate limits" (limiti di velocità) si applicano sia alle richieste HTTP della Batches API sia al numero di richieste all'interno di un batch in attesa di elaborazione. Consulta Limiti di velocità della Message Batches API. Inoltre, l'elaborazione potrebbe essere rallentata in base alla domanda corrente e al volume delle tue richieste. In tal caso, potresti vedere più richieste scadere dopo 24 ore.
• A causa dell'elevato throughput e dell'elaborazione concorrente, i batch potrebbero superare leggermente il limite di spesa configurato per il tuo Workspace.
• Ogni richiesta in batch deve avere max_tokens pari ad almeno 1. max_tokens: 0 (pre-riscaldamento della cache) non è supportato all'interno di un batch, perché una voce di cache effimera scritta durante l'elaborazione del batch probabilmente scadrebbe prima dell'esecuzione della richiesta successiva.

Modelli supportati

Tutti i modelli attivi supportano la Message Batches API.

Cosa può essere inserito in un batch

Quasi tutte le richieste che puoi effettuare alla Messages API possono essere incluse in un batch. Questo include:

• Vision
• "Tool use" (uso degli strumenti), inclusi tutti gli strumenti server (web search, web fetch, code execution, connettori MCP, advisor e tool search)
• Messaggi di sistema
• Conversazioni multi-turno
• "Extended thinking" (pensiero esteso)
• La maggior parte delle funzionalità beta

Poiché ogni richiesta nel batch viene elaborata in modo indipendente, puoi combinare diversi tipi di richieste all'interno di un singolo batch.

Un piccolo numero di parametri della Messages API non è supportato nelle richieste batch. L'inclusione di uno qualsiasi di questi restituisce un errore di validazione:

Prezzi

La Batches API offre risparmi significativi sui costi. Tutto l'utilizzo viene addebitato al 50% dei prezzi standard dell'API.

Come usare la Message Batches API

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 comprende:

• Un custom_id univoco per identificare la richiesta Messages. Deve essere compreso tra 1 e 64 caratteri e contenere solo caratteri alfanumerici, trattini e underscore (corrispondente a ^[a-zA-Z0-9_-]{1,64}$).
• Un oggetto params con i parametri standard della Messages API

Puoi creare un batch passando questo elenco nel parametro requests:

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",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

In questo esempio, due richieste separate vengono raggruppate in un batch per l'elaborazione asincrona. Ogni richiesta ha un custom_id univoco e contiene i parametri standard che useresti per una chiamata alla Messages API.

Quando un batch viene creato per la prima volta, la risposta ha uno stato di elaborazione in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Monitoraggio 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 terminato l'elaborazione e i risultati sono pronti. Puoi monitorare lo stato del tuo batch visitando la Console o utilizzando l'endpoint di recupero.

Polling per il completamento del Message Batch

Per effettuare il polling di un Message Batch, avrai bisogno del suo id, che viene fornito nella risposta alla creazione di un batch o elencando i batch. Puoi implementare un ciclo di polling che controlla periodicamente lo stato del batch finché l'elaborazione non è terminata:

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)

Elencare tutti i Message Batches

Puoi elencare tutti i Message Batches nel tuo Workspace utilizzando l'endpoint di elenco. L'API supporta la paginazione, recuperando automaticamente pagine aggiuntive secondo necessità:

client = anthropic.Anthropic()

# Recupera automaticamente altre pagine secondo necessità.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recupero dei risultati del batch

Una volta terminata l'elaborazione del batch, ogni richiesta Messages nel batch ha un risultato. Esistono quattro tipi di risultato:

Il campo request_counts del batch mostra una panoramica dei tuoi risultati, indicando quante richieste hanno raggiunto ciascuno di questi quattro stati.

I risultati del batch sono disponibili per il download alla proprietà results_url del Message Batch e, se l'autorizzazione dell'organizzazione lo consente, nella Console. A causa delle dimensioni potenzialmente elevate dei risultati, si consiglia di recuperare i risultati in streaming anziché scaricarli tutti in una volta.

client = anthropic.Anthropic()

# Trasmetti in streaming il file dei risultati in blocchi efficienti in memoria, elaborandoli uno alla volta
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # Il corpo della richiesta deve essere corretto prima di inviarla di nuovo
                print(f"Validation error {result.custom_id}")
            else:
                # La richiesta può essere ritentata direttamente
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

I risultati sono 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 del tipo di risultato. Ecco un esempio di insieme di risultati:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-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","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 contiene un errore, il suo result.error sarà impostato sulla forma di errore standard.

Annullamento di un Message Batch

Puoi annullare un Message Batch attualmente in elaborazione utilizzando l'endpoint di annullamento. Immediatamente dopo l'annullamento, il processing_status di un batch sarà canceling. Puoi usare la stessa tecnica di polling descritta in precedenza per attendere che l'annullamento sia finalizzato. I batch annullati terminano con uno stato ended e possono contenere risultati parziali per le richieste elaborate prima dell'annullamento.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

La risposta mostra il batch in stato canceling:

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

Uso della cache dei prompt con i Message Batches

La Message Batches API supporta il "prompt caching" (cache dei prompt), consentendoti potenzialmente di ridurre i costi e i tempi di elaborazione per le richieste batch. Gli sconti sui prezzi derivanti dalla cache dei prompt e dai Message Batches possono cumularsi, offrendo risparmi ancora maggiori quando entrambe le funzionalità vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e concorrente, i cache hit vengono forniti secondo il principio del best-effort. Gli utenti in genere riscontrano tassi di cache hit compresi tra il 30% e il 98%, a seconda dei loro pattern di traffico.

Per massimizzare la probabilità di cache hit 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 evitare che le voci della cache scadano dopo la loro durata di 5 minuti.
3. Struttura le tue richieste in modo da condividere quanto più contenuto in cache possibile.

Esempio di implementazione della cache dei prompt in un batch:

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",
                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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-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 Orgoglio e pregiudizio contrassegnato con cache_control per aumentare la probabilità di cache hit.

Strumenti server e ciclo agentico

Tutti gli strumenti server (web search, web fetch, code execution, connettori MCP, advisor e tool search) funzionano nelle richieste batch. Il worker batch esegue lo stesso ciclo agentico lato server della Messages API sincrona.

Poiché non c'è una connessione aperta da mantenere, il ciclo batch esegue più iterazioni per turno rispetto a una richiesta sincrona prima di restituire stop_reason: "pause_turn". Se un risultato batch viene restituito con pause_turn, il turno non è terminato; puoi continuarlo inviando il contenuto dell'assistente in pausa in una richiesta successiva (batch o sincrona) esattamente come mostrato nel pattern di continuazione pause_turn.

Il worker batch limita inoltre web_search per organizzazione, in modo che l'elaborazione batch altamente concorrente non esaurisca il limite di velocità di web search della tua organizzazione. Il batch ritenta automaticamente le richieste limitate; non devi gestirlo tu stesso, ma batch di web search molto grandi potrebbero richiedere più tempo per essere completati.

Output esteso (beta)

L'header beta output-300k-2026-03-24 aumenta il limite di max_tokens a 300.000 per le richieste batch che utilizzano Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 o Claude Sonnet 4.6. Includi l'header per generare output molto più lunghi del limite standard di 128k max_tokens in un singolo turno.

Usa l'output esteso per la generazione di contenuti lunghi come bozze della lunghezza di un libro e documentazione tecnica, estrazione esaustiva di dati strutturati, grandi scaffold di generazione di codice e lunghe catene di ragionamento.

Una singola generazione da 300k token può richiedere più di un'ora per essere completata, quindi pianifica l'invio dei tuoi batch tenendo presente la finestra di elaborazione di 24 ore. Si applicano i prezzi batch standard (50% dei prezzi standard dell'API).

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",
                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)

Best practice per un batching efficace

Per ottenere il massimo dalla Batches API:

• Monitora regolarmente lo stato di elaborazione dei batch e implementa una logica di retry appropriata per le richieste non riuscite.
• Usa valori custom_id significativi per abbinare facilmente i risultati alle richieste, poiché l'ordine non è garantito.
• Considera di suddividere dataset molto grandi in più batch per una migliore gestibilità.
• Esegui una prova a secco di una singola forma di richiesta con la Messages API per evitare errori di validazione.

Risoluzione dei problemi comuni

Se riscontri un comportamento inatteso:

• Verifica che la dimensione totale della richiesta batch non superi 256 MB. Se la dimensione della richiesta è troppo grande, potresti ricevere un errore 413 request_too_large.
• Controlla di utilizzare modelli supportati per tutte le richieste nel batch.
• Assicurati che ogni richiesta nel batch abbia un custom_id univoco.
• Assicurati che siano trascorsi meno di 29 giorni dal momento created_at del batch (non dal momento ended_at dell'elaborazione). Se sono trascorsi più di 29 giorni, i risultati non saranno più visualizzabili.
• Conferma che il batch non sia stato annullato.

Nota che il fallimento di una richiesta in un batch non influisce sull'elaborazione delle altre richieste.

Archiviazione dei batch e privacy

• Isolamento del Workspace: i batch sono isolati all'interno del Workspace in cui vengono creati. Possono essere accessibili solo tramite richieste API nello stesso Workspace o da utenti con l'autorizzazione a visualizzare i batch del Workspace nella Console.

• Disponibilità dei risultati: i risultati dei batch sono disponibili per 29 giorni dopo la creazione del batch, consentendo ampio tempo per il recupero e l'elaborazione.

Conservazione dei dati

L'elaborazione batch archivia i dati di richiesta e risposta per un massimo di 29 giorni dopo la creazione del batch. Puoi eliminare un message batch in qualsiasi momento dopo l'elaborazione utilizzando l'endpoint DELETE /v1/messages/batches/{batch_id}. Per eliminare un batch in corso, annullalo prima. L'elaborazione asincrona richiede l'archiviazione lato server sia degli input che degli output fino al completamento del batch e al recupero dei risultati.

Per l'idoneità ZDR di tutte le funzionalità, consulta API e conservazione dei dati.

FAQ

Prossimi passi