Format JSONL et téléversement via l'API Files
På denna sida
Mis à jour le 2 novembre 2026 selon la documentation xAI : la réduction pour les lots est de 20 % sur les modèles de texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel
xai-sdk(client.batch.*; l’API Batch de xAI n’utilise pas le format OpenAI, donc le SDK OpenAI ne s’applique pas), et l’API Responses prime sur Chat Completions, un point de terminaison hérité chez xAI. Sources : Batch API · Référence REST · Tarification Batch.
Traitement par lots avec JSONL
Pour de grands volumes préparés à l’avance, un fichier JSONL est la voie la plus simple. Tu écris toutes tes requêtes dans un fichier, tu le téléverses via l’API Files, puis tu crées le lot à partir de ce fichier. Un seul fichier peut contenir jusqu’à 50 000 requêtes.
Structure du fichier JSONL
Un fichier JSONL (JSON Lines) contient un objet JSON par ligne. Chaque ligne représente une requête complète avec quatre champs :
{"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 identifiant unique dans le fichier ; il devient lebatch_request_iddans les résultatsmethod: toujours"POST"url: le point de terminaison cible, l’un des sept acceptésbody: le corps de la requête, conforme à la référence API de ce point de terminaison
Chaque ligne doit être un JSON valide et autonome : pas de virgule de séparation, pas de crochet englobant. Les points de terminaison peuvent être mélangés dans le même fichier ; chaque requête est routée indépendamment.
Générer un fichier JSONL en Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... jusqu'à 50 000 documents par fichier
]
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")
Téléversement via l’API Files
Tu téléverses le fichier via le point de terminaison /v1/files, sans aucun autre paramètre :
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Avec le 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}")
Créer le lot à partir du fichier
Le fichier n’est pas ajouté à un lot existant : tu le spécifies au moment de la création avec 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}")
Le fichier est ensuite lu en arrière-plan. Si même une seule ligne est invalide, le lot est annulé avec un message d’erreur. Le suivi et la récupération des résultats fonctionnent ensuite exactement comme pour un lot soumis via l’API.
Limites du format JSONL
- Maximum 50 000 requêtes par fichier
- Maximum 200 Mo par fichier
- Un
custom_idunique par ligne - Un lot créé à partir d’un fichier est scellé : tu ne peux pas lui ajouter d’éléments ultérieurement via l’API
Si ton lot dépasse ces limites, divise-le en plusieurs fichiers et crée un lot par fichier. Il n’y a aucune limite au nombre de lots par équipe.
Générer un fichier JSONL en 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");
Validation et débogage
Une seule ligne invalide annule tout le lot : valide le fichier avant de le téléverser. Un script simple couvre l’essentiel :
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")
Viktiga punkter
- Le format JSONL contient un objet JSON par ligne :
custom_id,method,url,body - Tu téléverses le fichier via
/v1/files, puis tu le spécifies lors de la création du lot (input_file_id) - Maximum 50 000 requêtes et 200 Mo par fichier ; au-delà, un lot par fichier
- Un lot créé à partir d’un fichier est scellé, et une seule ligne invalide l’annule entièrement
- Valide le fichier avant de le téléverser