Format JSONL et upload via Files API

L’approche en masse avec JSONL

Pour les volumes importants, la méthode JSONL est nettement supérieure à l’ajout requête par requête. Vous préparez un fichier contenant toutes vos requêtes, vous l’uploadez via la Files API, puis vous l’associez au batch. Cette approche permet de soumettre jusqu’à 50 000 requêtes en une seule opération.

Structure du fichier JSONL

Un fichier JSONL (JSON Lines) contient un objet JSON par ligne. Chaque ligne représente une requête complète :

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

Chaque ligne doit être un JSON valide et autonome. Pas de virgule de séparation, pas de crochet englobant. Les champs sont identiques à la méthode JSON : custom_id, method, url, body.

Générer 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-4.5",
                "messages": [
                    {"role": "system", "content": "Résumez 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 généré, 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 réponse 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

Après 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 à respecter :

• 50 000 requêtes maximum par fichier JSONL
• 200 MB maximum par fichier

Si votre lot dépasse ces limites, découpez-le en plusieurs fichiers. Vous pouvez ajouter plusieurs fichiers JSONL au même batch, ou créer plusieurs batchs.

Pour estimer la taille, comptez environ 500 octets à 2 Ko par requête texte simple. Un fichier de 50 000 requêtes courtes pèse généralement entre 25 et 100 MB.

Générer 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-4.5",
    messages: [
      { role: "user", content: `Resume : ${doc.text}` }
    ]
  }
}));

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

Validation et débogage

Contrairement à l’ajout JSON individuel, les erreurs dans un fichier JSONL ne sont détectées qu’au moment du traitement. Validez votre fichier avant l’upload :

• Vérifiez que chaque ligne est un JSON valide
• Vérifiez que tous les custom_id sont uniques
• Vérifiez que les endpoints (url) existent
• Vérifiez que la taille totale ne dépasse 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 clés à retenir

• Le format JSONL contient un objet JSON par ligne, sans séparateur
• L’upload se fait via la Files API avec le purpose batch
• Maximum 50 000 requêtes et 200 MB par fichier
• Validez le fichier avant l’upload pour éviter les erreurs silencieuses
• Pour les très gros volumes, découpez en plusieurs fichiers