JSONL-Format und Upload über die Files API
Auf dieser Seite
Aktualisiert am 2. November 2026 basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle (nicht 50 %), die Beispiele folgen dem REST-API-Standard und dem offiziellen
xai-sdk(client.batch.*; die Batch API von xAI verwendet nicht das Format von OpenAI, sodass das OpenAI SDK nicht anwendbar ist), und die Responses API geht der Chat Completions API vor, einem veralteten Endpunkt bei xAI. Quellen: Batch API · REST-Referenz · Batch-Preise.
Massenvverarbeitung mit JSONL
Für große Volumina, die im Voraus vorbereitet werden, ist eine JSONL-Datei der einfachste Weg. Sie schreiben alle Ihre Anfragen in eine Datei, laden diese über die Files API hoch und erstellen den Batch aus dieser Datei. Eine einzelne Datei kann bis zu 50.000 Anfragen enthalten.
Struktur der JSONL-Datei
Eine JSONL (JSON Lines)-Datei enthält pro Zeile ein JSON-Objekt. Jede Zeile stellt eine vollständige Anfrage mit vier Feldern dar:
{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Fassen Sie diesen Text in einem Satz zusammen: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Klassifizieren Sie diesen Ticket: Fehler, Feature oder Frage. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Übersetzen Sie dies ins Englische: ..."}]}}
custom_id: eine eindeutige Kennzeichnung innerhalb der Datei; sie wird zurbatch_request_idin den Ergebnissenmethod: immer"POST"url: das Ziel-Endpoint, einer der sieben akzeptiertenbody: der Anforderungskörper, der der API-Referenz für diesen Endpunkt entspricht
Jede Zeile muss gültiges, eigenständiges JSON sein: kein Trennkomma, keine umschließenden Klammern. Endpunkte können in derselben Datei gemischt werden; jede Anfrage wird unabhängig geroutet.
Generieren einer JSONL-Datei in Python
import json
documents = [
{"id": "doc-001", "text": "Erster Artikel zur Zusammenfassung..."},
{"id": "doc-002", "text": "Zweiter Artikel zur Zusammenfassung..."},
# ... bis zu 50.000 Dokumente pro Datei
]
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": "Fassen Sie in drei Sätzen zusammen."},
{"role": "user", "content": doc["text"]},
],
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
Upload über die Files API
Sie laden die Datei über den Endpunkt /v1/files hoch, ohne weitere Parameter:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Mit dem 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"Hochgeladene Datei: {fichier.id}")
Batch aus der Datei erstellen
Die Datei wird nicht einem bestehenden Batch hinzugefügt: Sie geben sie zum Zeitpunkt der Erstellung mit input_file_id an:
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 erstellt: {batch.batch_id}")
Die Datei wird im Hintergrund gelesen. Wenn auch nur eine Zeile ungültig ist, wird der Batch mit einer Fehlermeldung abgebrochen. Das Verfolgen und Abrufen der Ergebnisse funktioniert dann exakt wie bei einem Batch, der über die API übermittelt wurde.
JSONL-Format-Grenzen
- Maximum 50.000 Anfragen pro Datei
- Maximum 200 MB pro Datei
- eine eindeutige
custom_idpro Zeile - ein aus einer Datei erstellter Batch ist versiegelt: Sie können ihm später nicht über die API hinzufügen
Wenn Ihr Batch diese Grenzen überschreitet, teilen Sie ihn in mehrere Dateien auf und erstellen Sie einen Batch pro Datei. Es gibt keine Obergrenze für die Anzahl der Batches pro Team.
Generieren einer JSONL-Datei in JavaScript
import fs from "fs";
const documents = [
{ id: "doc-001", text: "Erster Artikel..." },
{ id: "doc-002", text: "Zweiter Artikel..." },
];
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: `Zusammenfassung: ${doc.text}` }
]
}
}));
fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");
Validierung und Debugging
Eine ungültige Zeile bricht den gesamten Batch ab: Validieren Sie die Datei, bevor Sie sie hochladen. Ein einfaches Skript deckt die wesentlichen Punkte ab:
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("Datei größer als 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"Zeile {i}: ungültiges JSON ({e})")
continue
cid = obj.get("custom_id")
if not cid or cid in ids:
erreurs.append(f"Zeile {i}: fehlende oder doppelte custom_id")
ids.add(cid)
if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
erreurs.append(f"Zeile {i}: ungültige Methode oder URL")
if not isinstance(obj.get("body"), dict):
erreurs.append(f"Zeile {i}: fehlender body")
if len(ids) > 50_000:
erreurs.append("mehr als 50.000 Anfragen")
return erreurs
print(valider_jsonl("batch_requests.jsonl") or "Datei ist gültig")
Kernaussagen
- Das JSONL-Format enthält pro Zeile ein JSON-Objekt:
custom_id,method,url,body - Sie laden die Datei über
/v1/fileshoch und geben sie beim Erstellen des Batches an (input_file_id) - Maximum 50.000 Anfragen und 200 MB pro Datei; darüber hinaus ein Batch pro Datei
- Ein aus einer Datei erstellter Batch ist versiegelt, und eine ungültige Zeile bricht ihn vollständig ab
- Validieren Sie die Datei, bevor Sie sie hochladen