JSONL-indeling en uploaden via de Files API
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van de xAI-documentatie: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen (niet 50%), voorbeelden volgen de REST API en de officiële
xai-sdk(client.batch.*; de Batch API van xAI gebruikt niet het OpenAI-formaat, dus de OpenAI SDK is niet van toepassing), en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST-referentie · Batch-prijzen.
Bulkverwerking met JSONL
Voor grote volumes die vooraf zijn voorbereid, is een JSONL-bestand de eenvoudigste route. U schrijft al uw verzoeken in een bestand, uploadt dit via de Files API en maakt vervolgens de batch op basis van dat bestand. Een enkel bestand kan tot 50.000 verzoeken bevatten.
Structuur van het JSONL-bestand
Een JSONL-bestand (JSON Lines) bevat één JSON-object per regel. Elke regel vertegenwoordigt een compleet verzoek met vier velden:
{"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: een unieke identificatie binnen het bestand; dit wordt debatch_request_idin de resultatenmethod: altijd"POST"url: het doeleindpunt, een van de zeven geaccepteerde optiesbody: de verzoektekst, overeenkomend met de API-referentie voor dat eindpunt
Elke regel moet geldige, op zichzelf staande JSON zijn: geen scheidingstekens met komma’s, geen omringende haken. Eindpunten kunnen binnen hetzelfde bestand worden gemengd; elk verzoek wordt onafhankelijk gerouteerd.
Een JSONL-bestand genereren in Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... tot 50.000 documenten per bestand
]
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")
Uploaden via de Files API
U uploadt het bestand via het /v1/files-eindpunt, zonder andere parameters:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Met de Python SDK:
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}")
De batch maken vanuit het bestand
Het bestand wordt niet toegevoegd aan een bestaande batch: u specificeert het op het moment van creatie met 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}")
Het bestand wordt vervolgens op de achtergrond gelezen. Als zelfs maar één regel ongeldig is, wordt de batch geannuleerd met een foutmelding. Het volgen en ophalen van resultaten werkt vervolgens exact hetzelfde als bij een batch die via de API is ingediend.
Limieten van het JSONL-formaat
- Maximum 50.000 verzoeken per bestand
- Maximum 200 MB per bestand
- een unieke
custom_idper regel - een batch die vanuit een bestand is gemaakt, is verzegeld: u kunt er later niets meer aan toevoegen via de API
Als uw batch deze limieten overschrijdt, splitst u deze op in meerdere bestanden en maakt u één batch per bestand. Er is geen limiet op het aantal batches per team.
Een JSONL-bestand genereren 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");
Validatie en foutopsporing
Eén ongeldige regel annuleert de volledige batch: valideer het bestand voordat u het uploadt. Een eenvoudig script dekt de basisbehoeften:
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")
Belangrijkste punten
- Het JSONL-formaat bevat één JSON-object per regel:
custom_id,method,url,body - U uploadt het bestand via
/v1/filesen specificeert het vervolgens bij het maken van de batch (input_file_id) - Maximum 50.000 verzoeken en 200 MB per bestand; daarboven geldt één batch per bestand
- Een batch die vanuit een bestand is gemaakt, is verzegeld en één ongeldige regel annuleert deze volledig
- Valideer het bestand voordat u het uploadt