Formato JSONL y carga mediante la API de archivos
En esta página
Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %), los ejemplos siguen la API REST y el
xai-sdkoficial (client.batch.*; la API de lotes de xAI no utiliza el formato de OpenAI, por lo que el SDK de OpenAI no es aplicable), y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: API de lotes · Referencia REST · Precios de lotes.
Procesamiento por lotes con JSONL
Para grandes volúmenes preparados con antelación, un archivo JSONL es la vía más sencilla. Escribes todas tus solicitudes en un archivo, lo subes a través de la API de archivos y, a continuación, creas el lote a partir de dicho archivo. Un único archivo puede contener hasta 50.000 solicitudes.
Estructura del archivo JSONL
Un archivo JSONL (JSON Lines) contiene un objeto JSON por línea. Cada línea representa una solicitud completa con cuatro campos:
{"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 identificador único dentro del archivo; se convierte en elbatch_request_iden los resultados.method: siempre"POST".url: el punto final de destino, uno de los siete aceptados.body: el cuerpo de la solicitud, que debe coincidir con la referencia de la API para ese punto final.
Cada línea debe ser un JSON válido y autónomo: sin comas separadoras ni corchetes de cierre. Los puntos finales pueden mezclarse en el mismo archivo; cada solicitud se enruta de forma independiente.
Generar un archivo JSONL en Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... up to 50,000 documents per file
]
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")
Carga mediante la API de archivos
Subes el archivo a través del punto final /v1/files, sin ningún otro parámetro:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Con el SDK de 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}")
Crear el lote a partir del archivo
El archivo no se añade a un lote existente: debes especificarlo en el momento de la creación mediante 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}")
A continuación, el archivo se lee en segundo plano. Si siquiera una línea no es válida, el lote se cancela con un mensaje de error. El seguimiento y la recuperación de resultados funcionan exactamente igual que para un lote enviado a través de la API.
Límites del formato JSONL
- Máximo 50.000 solicitudes por archivo.
- Máximo 200 MB por archivo.
- Un
custom_idúnico por línea. - Un lote creado a partir de un archivo está sellado: no puedes añadirle contenido posteriormente a través de la API.
Si tu lote supera estos límites, divídelo en varios archivos y crea un lote por archivo. No hay límite en el número de lotes por equipo.
Generar un archivo 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");
Validación y depuración
Una sola línea no válida cancela todo el lote: valida el archivo antes de subirlo. Un script sencillo cubre lo esencial:
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")
Puntos clave
- El formato JSONL contiene un objeto JSON por línea:
custom_id,method,url,body. - Subes el archivo a través de
/v1/filesy luego lo especificas al crear el lote (input_file_id). - Máximo 50.000 solicitudes y 200 MB por archivo; más allá de eso, un lote por archivo.
- Un lote creado a partir de un archivo está sellado y una sola línea no válida lo cancela por completo.
- Valida el archivo antes de subirlo.