Creare un batch vuoto
In questa pagina
Aggiornato il 2 novembre 2026 in base alla documentazione xAI: lo sconto per i batch è del 20% sui modelli di testo idonei (non del 50%), gli esempi utilizzano l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non utilizza il formato di OpenAI, quindi l’SDK OpenAI non si applica) e l’API Responses ha la priorità rispetto a Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Primo passo: inizializzazione
La creazione di un batch è la prima azione concreta nel tuo flusso di lavoro. Una chiamata POST /v1/batches inizializza un contenitore vuoto che riceverà successivamente le tue richieste. Questo passaggio è volutamente minimale: crea l’identificativo e prepara il batch lato server.
POST /v1/batches
Crea un batch denominato e restituisce il suo batch_id.
Salva il batch_id
Salva l'identificativo per le operazioni successive.
Aggiungi le richieste
Il batch è pronto a ricevere richieste tramite l'API.
La chiamata di creazione
Il corpo della richiesta contiene un solo campo obbligatorio, name:
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
La risposta contiene il batch_id, le date di creazione e scadenza, e i contatori del batch, ancora a zero (esempio dal riferimento API):
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "customer_review_analysis",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": null,
"cancel_by_xai_message": null,
"state": {
"num_requests": 0,
"num_pending": 0,
"num_success": 0,
"num_error": 0,
"num_cancelled": 0
}
}
Implementazione in Python
L’SDK ufficiale si installa con pip install xai-sdk (versione 1.21.0 al 2 novembre 2026; Python 3.10 minimo). Legge la chiave dalla variabile d’ambiente XAI_API_KEY:
from xai_sdk import Client
client = Client()
batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Batch creato: {batch_id}")
Il batch_id restituito è il riferimento univoco per il tuo batch. Conservalo in una variabile, in un file o in un database, a seconda della tua architettura.
Implementazione in JavaScript
Senza un SDK, è sufficiente una semplice chiamata fetch all’API REST:
const response = await fetch("https://api.x.ai/v1/batches", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ name: "customer_review_analysis" })
});
const batch = await response.json();
console.log(`Batch creato: ${batch.batch_id}`);
Limiti di velocità per la creazione
La creazione di batch è limitata a 2 al secondo per team; il numero totale di batch non ha limiti. In pratica, raramente raggiungerai questo limite: generalmente crei un batch per operazione, poi aggiungi tutte le richieste ad esso. Se ne crei diversi in un ciclo, distanzia le chiamate di almeno 500 millisecondi.
Buone pratiche
Assegna nomi significativi ai batch: il nome è obbligatorio, quindi rendilo utile. Un nome che indica il dataset e la data (customer_reviews_2026_11_02) è facile da trovare nell’elenco dei batch e nella console xAI, che ti permette anche di tracciare i batch visivamente.
Prendi nota della scadenza: expire_time indica quando il batch e i suoi risultati smettono di essere accessibili. Il tuo processo di recupero deve essere eseguito prima di tale momento.
Gestisci gli errori di creazione: un errore di autenticazione, il superamento del limite di velocità o un problema di rete possono impedire la creazione. Riprova gli errori transitori con un ritardo crescente (backoff esponenziale), ma non riprovare mai in caso di errori di autenticazione.
Punti chiave
- Creare un batch è una
POST /v1/batchesil cui unico campo obbligatorio èname - La risposta contiene un
batch_idunivoco da conservare per il resto del flusso di lavoro - In Python, l’SDK ufficiale
xai-sdkesponeclient.batch.create(batch_name=...) - Il limite è di 2 creazioni al secondo per team, senza limiti sul numero di batch
- Controlla
expire_timee riprova solo gli errori transitori