Format JSONL și încărcare prin API-ul Files
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%), exemplele urmează API-ul REST și SDK-ul oficial
xai-sdk(client.batch.*; API-ul Batch al xAI nu folosește formatul OpenAI, deci SDK-ul OpenAI nu se aplică), iar API-ul Responses are prioritate față de Chat Completions, un endpoint moștenit la xAI. Surse: Batch API · Referință REST · Prețuri Batch.
Procesare în masă cu JSONL
Pentru volume mari pregătite în avans, un fișier JSONL reprezintă cea mai simplă soluție. Scrieți toate cererile într-un fișier, îl încărcați prin API-ul Files, apoi creați lotul pe baza acelui fișier. Un singur fișier poate conține până la 50.000 de cereri.
Structura fișierului JSONL
Un fișier JSONL (JSON Lines) conține un obiect JSON pe fiecare linie. Fiecare linie reprezintă o cerere completă cu patru câmpuri:
{"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 identificator unic în cadrul fișierului; devinebatch_request_idîn rezultatemethod: întotdeauna"POST"url: endpoint-ul țintă, unul dintre cele șapte acceptatebody: corpul cererii, corespunzător referinței API pentru acel endpoint
Fiecare linie trebuie să fie un JSON valid și autonom: fără virgulă de separare, fără paranteze de încadrare. Endpoint-urile pot fi amestecate în același fișier; fiecare cerere este dirijată independent.
Generarea unui fișier JSONL în Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... până la 50.000 de documente per fișier
]
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")
Încărcare prin API-ul Files
Încărcați fișierul prin endpoint-ul /v1/files, fără alți parametri:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Cu SDK-ul 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}")
Crearea lotului din fișier
Fișierul nu este adăugat unui lot existent: îl specificați la momentul creării cu 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}")
Fișierul este apoi citit în fundal. Dacă chiar și o singură linie este invalidă, lotul este anulat cu un mesaj de eroare. Urmărirea și recuperarea rezultatelor funcționează exact ca pentru un lot trimis prin API.
Limitele formatului JSONL
- Maxim 50.000 de cereri per fișier
- Maxim 200 MB per fișier
- Un
custom_idunic pe linie - Un lot creat dintr-un fișier este sigilat: nu îi puteți adăuga elemente ulterior prin API
Dacă lotul dumneavoastră depășește aceste limite, divizați-l în mai multe fișiere și creați câte un lot per fișier. Nu există o limită a numărului de loturi per echipă.
Generarea unui fișier JSONL în 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");
Validare și depanare
O singură linie invalidă anulează întregul lot: validați fișierul înainte de a-l încărca. Un script simplu acoperă esențialul:
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")
Puncte cheie
- Formatul JSONL conține un obiect JSON pe linie:
custom_id,method,url,body - Încărcați fișierul prin
/v1/files, apoi îl specificați la crearea lotului (input_file_id) - Maxim 50.000 de cereri și 200 MB per fișier; dincolo de aceste limite, creați câte un lot per fișier
- Un lot creat dintr-un fișier este sigilat, iar o singură linie invalidă îl anulează în totalitate
- Validați fișierul înainte de încărcare