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:

• Visione
• "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" (ragionamento 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.

Model	Batch tokens
Name	Input	Output
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$5 / MTok	$25 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work	$2 / MTok	$10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence	$1 / MTok	$5 / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	$0.05 / MTokfor prompts up to 100,000 tokens	$0.25 / MTok
	$0.25 / MTokfor prompts over 100,000 tokens	$1.25 / MTok
Additional models
Claude Mythos 5.1	$5 / MTok	$25 / MTok
Claude Fable 5	$5 / MTok	$25 / MTok
Claude Mythos 5	$5 / MTok	$25 / 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	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / 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	$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

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

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()