Formato JSONL e caricamento tramite Files API
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 seguono le API REST e l’SDK ufficiale
xai-sdk(client.batch.*; le Batch API di xAI non usano il formato OpenAI, quindi l’SDK OpenAI non si applica), e le Responses API hanno la priorità rispetto alle Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Elaborazione in blocco con JSONL
Per grandi volumi di dati preparati in anticipo, un file JSONL è la via più semplice. Scrivi tutte le tue richieste in un file, lo carichi tramite le Files API, quindi crei il batch da quel file. Un singolo file può contenere fino a 50.000 richieste.
Struttura del file JSONL
Un file JSONL (JSON Lines) contiene un oggetto JSON per riga. Ogni riga rappresenta una richiesta completa con quattro campi:
{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Summarize this text in one sentence: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Classify this ticket: bug, feature, or question. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Translate into English: ..."}]}}
custom_id: un identificatore univoco all’interno del file; diventa ilbatch_request_idnei risultatimethod: sempre"POST"url: l’endpoint di destinazione, uno dei sette accettatibody: il corpo della richiesta, conforme al riferimento API per quell’endpoint
Ogni riga deve essere un JSON valido e autonomo: nessuna virgola di separazione, nessuna parentesi di chiusura. Gli endpoint possono essere mescolati nello stesso file; ogni richiesta viene instradata indipendentemente.
Generare un file JSONL in Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... fino a 50.000 documenti per file
]
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Summarize in three sentences."},
{"role": "user", "content": doc["text"]},
],
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
Caricamento tramite Files API
Carichi il file tramite l’endpoint /v1/files, senza altri parametri:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Con l’SDK Python:
from xai_sdk import Client
client = Client()
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Uploaded file: {fichier.id}")
Creare il batch dal file
Il file non viene aggiunto a un batch esistente: lo specifichi al momento della creazione con input_file_id:
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "article_summaries", "input_file_id": "file-abc123"}'
batch = client.batch.create(batch_name="article_summaries", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")
Il file viene quindi letto in background. Se anche una sola riga non è valida, il batch viene annullato con un messaggio di errore. Il monitoraggio e il recupero dei risultati funzionano esattamente come per un batch inviato tramite API.
Limiti del formato JSONL
- Massimo 50.000 richieste per file
- Massimo 200 MB per file
- un
custom_idunivoco per riga - un batch creato da un file è sigillato: non puoi aggiungergli elementi in seguito tramite API
Se il tuo batch supera questi limiti, dividilo in più file e crea un batch per file. Non c’è limite al numero di batch per team.
Generare un file JSONL in JavaScript
import fs from "fs";
const documents = [
{ id: "doc-001", text: "First article..." },
{ id: "doc-002", text: "Second article..." },
];
const lines = documents.map(doc => JSON.stringify({
custom_id: doc.id,
method: "POST",
url: "/v1/responses",
body: {
model: "grok-4.3",
input: [
{ role: "user", content: `Summarize: ${doc.text}` }
]
}
}));
fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");
Validazione e debug
Una singola riga non valida annulla l’intero batch: valida il file prima di caricarlo. Uno script semplice copre l’essenziale:
import json
import os
ENDPOINTS = {
"/v1/responses", "/v1/chat/completions",
"/v1/images/generations", "/v1/images/edits",
"/v1/videos/generations", "/v1/videos", "/v1/videos/edits", "/v1/videos/extensions",
}
def valider_jsonl(chemin: str) -> list[str]:
erreurs, ids = [], set()
if os.path.getsize(chemin) > 200 * 1024 * 1024:
erreurs.append("file larger than 200 MB")
with open(chemin, encoding="utf-8") as f:
for i, ligne in enumerate(f, 1):
try:
obj = json.loads(ligne)
except json.JSONDecodeError as e:
erreurs.append(f"line {i}: invalid JSON ({e})")
continue
cid = obj.get("custom_id")
if not cid or cid in ids:
erreurs.append(f"line {i}: missing or duplicate custom_id")
ids.add(cid)
if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
erreurs.append(f"line {i}: invalid method or url")
if not isinstance(obj.get("body"), dict):
erreurs.append(f"line {i}: missing body")
if len(ids) > 50_000:
erreurs.append("more than 50,000 requests")
return erreurs
print(valider_jsonl("batch_requests.jsonl") or "File is valid")
Punti chiave
- Il formato JSONL contiene un oggetto JSON per riga:
custom_id,method,url,body - Carichi il file tramite
/v1/files, quindi lo specifichi durante la creazione del batch (input_file_id) - Massimo 50.000 richieste e 200 MB per file; oltre tale limite, un batch per file
- Un batch creato da un file è sigillato e una singola riga non valida lo annulla interamente
- Valida il file prima di caricarlo