Formato JSONL e carregamento através da API de Ficheiros
Nesta página
Atualizado em 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (não 50%), os exemplos seguem a API REST e o
xai-sdkoficial (client.batch.*; a API de Lotes da xAI não utiliza o formato da OpenAI, pelo que o SDK da OpenAI não se aplica), e a API de Respostas tem precedência sobre as Conclusões de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.
Processamento em massa com JSONL
Para grandes volumes preparados antecipadamente, um ficheiro JSONL é o caminho mais simples. Escreve todos os seus pedidos num ficheiro, carrega-o através da API de Ficheiros e, em seguida, cria o lote a partir desse ficheiro. Um único ficheiro pode conter até 50.000 pedidos.
Estrutura do ficheiro JSONL
Um ficheiro JSONL (JSON Lines) contém um objeto JSON por linha. Cada linha representa um pedido completo com quatro 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: um identificador único dentro do ficheiro; torna-se nobatch_request_idnos resultadosmethod: sempre"POST"url: o endpoint de destino, um dos sete aceitesbody: o corpo do pedido, correspondendo à referência da API para esse endpoint
Cada linha deve ser um JSON válido e autónomo: sem vírgula de separação, sem parênteses retos de envolvimento. Os endpoints podem ser misturados no mesmo ficheiro; cada pedido é encaminhado independentemente.
Gerar um ficheiro JSONL em 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:
linha = {
"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(linha, ensure_ascii=False) + "\n")
Carregamento através da API de Ficheiros
Carrega o ficheiro através do endpoint /v1/files, sem quaisquer outros parâmetros:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Com o SDK Python:
from xai_sdk import Client
client = Client()
with open("batch_requests.jsonl", "rb") as f:
ficheiro = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Uploaded file: {ficheiro.id}")
Criar o lote a partir do ficheiro
O ficheiro não é adicionado a um lote existente: especifica-o no momento da criação com 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"}'
lote = client.batch.create(batch_name="article_summaries", input_file_id=ficheiro.id)
print(f"Batch created: {lote.batch_id}")
O ficheiro é então lido em segundo plano. Se mesmo uma linha for inválida, o lote é cancelado com uma mensagem de erro. O acompanhamento e a recuperação de resultados funcionam exatamente como para um lote submetido através da API.
Limites do formato JSONL
- Máximo de 50.000 pedidos por ficheiro
- Máximo de 200 MB por ficheiro
- um
custom_idúnico por linha - um lote criado a partir de um ficheiro está selado: não lhe pode adicionar nada posteriormente através da API
Se o seu lote exceder estes limites, divida-o em vários ficheiros e crie um lote por ficheiro. Não existe limite para o número de lotes por equipa.
Gerar um ficheiro JSONL em 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");
Validação e depuração
Uma linha inválida cancela todo o lote: valide o ficheiro antes de o carregar. Um script simples cobre o essencial:
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 validar_jsonl(caminho: str) -> list[str]:
erros, ids = [], set()
if os.path.getsize(caminho) > 200 * 1024 * 1024:
erros.append("file larger than 200 MB")
with open(caminho, encoding="utf-8") as f:
for i, linha in enumerate(f, 1):
try:
obj = json.loads(linha)
except json.JSONDecodeError as e:
erros.append(f"line {i}: invalid JSON ({e})")
continue
cid = obj.get("custom_id")
if not cid or cid in ids:
erros.append(f"line {i}: missing or duplicate custom_id")
ids.add(cid)
if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
erros.append(f"line {i}: invalid method or url")
if not isinstance(obj.get("body"), dict):
erros.append(f"line {i}: missing body")
if len(ids) > 50_000:
erros.append("more than 50,000 requests")
return erros
print(validar_jsonl("batch_requests.jsonl") or "File is valid")
Pontos-chave
- O formato JSONL contém um objeto JSON por linha:
custom_id,method,url,body - Carrega o ficheiro através de
/v1/filese especifica-o ao criar o lote (input_file_id) - Máximo de 50.000 pedidos e 200 MB por ficheiro; além disso, um lote por ficheiro
- Um lote criado a partir de um ficheiro está selado e uma linha inválida cancela-o totalmente
- Valide o ficheiro antes de o carregar