Aggiungere richieste in JSON
In questa pagina
Aggiornato il 2 novembre 2026 sulla base della documentazione xAI: lo sconto per i batch è del 20% sui modelli di testo idonei (non del 50%), gli esempi seguono l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non utilizza il formato OpenAI, quindi l’SDK OpenAI non si applica) e le API Responses hanno la priorità rispetto alle Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Aggiunta tramite API
Una volta creato il batch, aggiungi le richieste utilizzando POST /v1/batches/{batch_id}/requests. Ogni chiamata trasporta un elenco di richieste e puoi invocare l’endpoint quante volte necessario, purché il batch non sia stato annullato. Questo approccio è ideale per i batch costruiti in modo incrementale.
Struttura della richiesta
Il corpo della chiamata contiene un array batch_requests. Ogni elemento associa un identificatore (batch_request_id) alla richiesta vera e propria, archiviata sotto la chiave corrispondente al suo tipo: responses per le API Responses:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Classifica il sentiment: positivo, negativo o neutro."},
{"role": "user", "content": "Il prodotto ha superato le mie aspettative!"}
]
}
}
}
]
}
batch_request_id: Il tuo identificatore, unico all’interno del batch. È la chiave che collega la richiesta al suo risultato; se mancante, xAI genera un UUID.batch_request: La richiesta, inserita sotto la chiave del suo tipo; il riferimento API documenta anchechat_get_completionper il formato Chat Completions.
Per immagini e video, utilizza l’SDK (lezione 9) o un file JSONL (prossima lezione).
Richiesta cURL
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_requests": [
{
"batch_request_id": "article-42",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "user", "content": "Classifica questo testo: positivo, neutro o negativo."}
]
}
}
}
]
}'
Aggiunta con l’SDK Python
Con l’SDK, ogni richiesta viene costruita come una conversazione standard, assegnandole un batch_request_id; successivamente le aggiungi a blocchi:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "Primo documento da analizzare..."},
{"id": "doc-2", "text": "Secondo documento da analizzare..."},
{"id": "doc-3", "text": "Terzo documento da analizzare..."},
]
batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"
requests = []
for doc in documents:
chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
chat.append(system("Riassumi il documento in due frasi."))
chat.append(user(doc["text"]))
requests.append(chat)
# Aggiungi a blocchi di 100: una chiamata API per blocco
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
La documentazione non impone un numero massimo di richieste per chiamata; dimensioni moderate dei blocchi limitano semplicemente la quantità di dati da reinviare in caso di problemi di rete.
Limiti di frequenza per l’aggiunta
Un team può effettuare fino a 1.000 chiamate di aggiunta ogni 30 secondi, in una finestra scorrevole condivisa tra tutti i suoi batch. Il limite si applica alle chiamate, non alle singole richieste: con blocchi di 100 richieste, questo consente già di elaborare oltre 3.000 richieste al secondo. Due altri vincoli sono più rilevanti:
- 25 MB massimi per singola richiesta, aspetto che riguarda principalmente le immagini codificate in base64.
- Oltre 100.000 richieste in un batch, xAI potrebbe rallentare l’elaborazione per preservare la stabilità del servizio.
Quando utilizzare l’aggiunta via API
L’aggiunta via API è preferibile quando la flessibilità conta più della preparazione iniziale. Diventa la scelta naturale quando il batch viene costruito in modo incrementale: le richieste che arrivano da una coda vengono aggiunte man mano che pervengono, mentre un file JSONL richiederebbe di conoscere tutto in anticipo e chiuderebbe il batch. È anche la strada maestra per il prototipaggio, per testare l’intero flusso di lavoro con cinque richieste prima di scalare, e per gestire batch eterogenei.
Validazione delle richieste
Controlla il codice di stato di ogni chiamata di aggiunta: un errore in questa fase significa che il blocco non è stato salvato e devi reinviarlo. Una richiesta può anche fallire successivamente, durante l’elaborazione; in tal caso apparirà nei risultati con il relativo messaggio di errore. Un modello che non accetta il batch viene rifiutato con il messaggio not supported for batch processing: verifica l’idoneità nella pagina del modello prima di lanciare un batch di grandi dimensioni.
Punti chiave
- L’aggiunta avviene tramite
POST /v1/batches/{id}/requests, con un elencobatch_requests. - Ogni richiesta include un
batch_request_idunico e il suo contenuto sotto la chiave del tipo (responses,chat_get_completion). - L’SDK costruisce le richieste con
client.chat.create(..., batch_request_id=...)e le aggiunge conclient.batch.add. - Il limite è di 1.000 chiamate di aggiunta ogni 30 secondi per team; ogni chiamata può trasportare molte richieste.
- A differenza del file JSONL, l’aggiunta via API lascia il batch aperto a nuove aggiunte.