Formát JSONL a nahrávání přes Files API
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace xAI: sleva pro batch je 20 % u způsobilých textových modelů (nikoli 50 %), příklady následují REST API a oficiální
xai-sdk(client.batch.*; Batch API od xAI nepoužívá formát OpenAI, takže SDK od OpenAI není použitelné) a Responses API má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · Reference REST · Ceník Batch.
Hromadné zpracování s JSONL
Pro velké objemy dat připravené předem je soubor JSONL nejjednodušší cestou. Všechny své požadavky zapíšeš do souboru, nahraješ jej přes Files API a následně z tohoto souboru vytvoříš batch. Jeden soubor může obsahovat až 50 000 požadavků.
Struktura souboru JSONL
Soubor JSONL (JSON Lines) obsahuje jeden objekt JSON na řádek. Každý řádek představuje úplný požadavek se čtyřmi poli:
{"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: jedinečný identifikátor v rámci souboru; ve výsledcích se stanebatch_request_idmethod: vždy"POST"url: cílový koncový bod, jeden ze sedmi přijímanýchbody: tělo požadavku odpovídající referenci API pro daný koncový bod
Každý řádek musí být platný, samostatný JSON: žádná oddělující čárka, žádné uzavírací závorky. Koncové body lze v jednom souboru kombinovat; každý požadavek je směrován nezávisle.
Generování souboru JSONL v Pythonu
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... až 50 000 dokumentů na soubor
]
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")
Nahrávání přes Files API
Soubor nahraješ přes koncový bod /v1/files bez dalších parametrů:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
S 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}")
Vytvoření batche ze souboru
Soubor se nepřidává do existujícího batche: určíš jej přímo při vytváření pomocí 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}")
Soubor je následně čten na pozadí. Pokud je byť jen jeden řádek neplatný, je batch zrušen s chybovou zprávou. Sledování a získávání výsledků pak funguje přesně stejně jako u batche odeslaného přímo přes API.
Limity formátu JSONL
- Maximálně 50 000 požadavků na soubor
- Maximálně 200 MB na soubor
- jedinečné
custom_idna každý řádek - batch vytvořený ze souboru je uzavřený: nelze jej později přes API rozšířit
Pokud tvůj batch tyto limity překračuje, rozděl jej na více souborů a vytvoř jeden batch na každý soubor. Počet batchů na tým není omezen.
Generování souboru JSONL v JavaScriptu
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");
Validace a ladění
Jeden neplatný řádek zruší celý batch: před nahráním soubor validuj. Jednoduchý skript pokryje to podstatné:
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")
Klíčové poznatky
- Formát JSONL obsahuje jeden objekt JSON na řádek:
custom_id,method,url,body - Soubor nahraješ přes
/v1/filesa poté jej uvedeš při vytváření batche (input_file_id) - Maximum 50 000 požadavků a 200 MB na soubor; při překročení vytvoř jeden batch na soubor
- Batch vytvořený ze souboru je uzavřený a jeden neplatný řádek jej celý zruší
- Před nahráním soubor validuj