Format JSONL et upload via Files API

L’approche en masse avec JSONL

Pour les volumes importants, la methode JSONL est nettement superieure a l’ajout requete par requete. Vous preparez un fichier contenant toutes vos requetes, vous l’uploadez via la Files API, puis vous l’associez au batch. Cette approche permet de soumettre jusqu’a 50 000 requetes en une seule operation.

Structure du fichier JSONL

Un fichier JSONL (JSON Lines) contient un objet JSON par ligne. Chaque ligne represente une requete complete :

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-3", "messages": [{"role": "user", "content": "Resumez ce texte en une phrase."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-3", "messages": [{"role": "user", "content": "Classifiez ce ticket : bug, feature, question."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-3", "messages": [{"role": "user", "content": "Traduisez en anglais."}]}}

Chaque ligne doit etre un JSON valide et autonome. Pas de virgule de separation, pas de crochet englobant. Les champs sont identiques a la methode JSON : custom_id, method, url, body.

Generer un fichier JSONL en Python

import json

documents = [
    {"id": "doc-001", "text": "Premier article a resumer..."},
    {"id": "doc-002", "text": "Deuxieme article a resumer..."},
    # ... jusqu'a 50 000 documents
]

with open("batch_requests.jsonl", "w") as f:
    for doc in documents:
        request = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/chat/completions",
            "body": {
                "model": "grok-3",
                "messages": [
                    {"role": "system", "content": "Resumez en 3 phrases."},
                    {"role": "user", "content": doc["text"]}
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Upload via la Files API

Une fois le fichier JSONL genere, uploadez-le avec le purpose batch :

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "file=@batch_requests.jsonl" \
  -F "purpose=batch"

La reponse contient un file_id que vous utiliserez pour associer le fichier au batch :

{
  "id": "file_xyz789",
  "filename": "batch_requests.jsonl",
  "purpose": "batch",
  "bytes": 1048576
}

Associer le fichier au batch

Apres l’upload, associez le fichier au batch existant :

curl -X POST "https://api.x.ai/v1/batches/${BATCH_ID}/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_id\": \"file_xyz789\"}"

Limites du format JSONL

Deux contraintes a respecter :

• 50 000 requetes maximum par fichier JSONL
• 200 MB maximum par fichier

Si votre lot depasse ces limites, decoupez-le en plusieurs fichiers. Vous pouvez ajouter plusieurs fichiers JSONL au meme batch, ou creer plusieurs batchs.

Pour estimer la taille, comptez environ 500 octets a 2 Ko par requete texte simple. Un fichier de 50 000 requetes courtes pese generalement entre 25 et 100 MB.

Generer un JSONL en JavaScript

import fs from "fs";

const documents = [
  { id: "doc-001", text: "Premier article..." },
  { id: "doc-002", text: "Deuxieme article..." },
];

const lines = documents.map(doc => JSON.stringify({
  custom_id: doc.id,
  method: "POST",
  url: "/v1/chat/completions",
  body: {
    model: "grok-3",
    messages: [
      { role: "user", content: `Resume : ${doc.text}` }
    ]
  }
}));

fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");

Validation et debogage

Contrairement a l’ajout JSON individuel, les erreurs dans un fichier JSONL ne sont detectees qu’au moment du traitement. Validez votre fichier avant l’upload :

• Verifiez que chaque ligne est un JSON valide
• Verifiez que tous les custom_id sont uniques
• Verifiez que les endpoints (url) existent
• Verifiez que la taille totale ne depasse pas 200 MB

Un script de validation simple :

import json

with open("batch_requests.jsonl") as f:
    ids = set()
    for i, line in enumerate(f, 1):
        try:
            obj = json.loads(line)
            assert "custom_id" in obj, "custom_id manquant"
            assert obj["custom_id"] not in ids, f"custom_id duplique : {obj['custom_id']}"
            ids.add(obj["custom_id"])
        except (json.JSONDecodeError, AssertionError) as e:
            print(f"Erreur ligne {i}: {e}")

Points cles a retenir

• Le format JSONL contient un objet JSON par ligne, sans separateur
• L’upload se fait via la Files API avec le purpose batch
• Maximum 50 000 requetes et 200 MB par fichier
• Validez le fichier avant l’upload pour eviter les erreurs silencieuses
• Pour les tres gros volumes, decoupez en plusieurs fichiers