Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Format JSONL et téléversement via l'API Files

Lektion 6 av 12 Uppdaterad 2 november 2026 Utvecklare
På denna sida
  1. Traitement par lots avec JSONL
  2. Structure du fichier JSONL
  3. Générer un fichier JSONL en Python
  4. Téléversement via l’API Files
  5. Créer le lot à partir du fichier
  6. Limites du format JSONL
  7. Générer un fichier JSONL en JavaScript
  8. Validation et débogage
  9. Viktiga punkter

Mis à jour le 2 novembre 2026 selon la documentation xAI : la réduction pour les lots est de 20 % sur les modèles de texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel xai-sdk (client.batch.* ; l’API Batch de xAI n’utilise pas le format OpenAI, donc le SDK OpenAI ne s’applique pas), et l’API Responses prime sur Chat Completions, un point de terminaison hérité chez xAI. Sources : Batch API · Référence REST · Tarification Batch.

Traitement par lots avec JSONL

Pour de grands volumes préparés à l’avance, un fichier JSONL est la voie la plus simple. Tu écris toutes tes requêtes dans un fichier, tu le téléverses via l’API Files, puis tu crées le lot à partir de ce fichier. Un seul fichier peut contenir jusqu’à 50 000 requêtes.

Structure du fichier JSONL

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

{"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 identifiant unique dans le fichier ; il devient le batch_request_id dans les résultats
  • method : toujours "POST"
  • url : le point de terminaison cible, l’un des sept acceptés
  • body : le corps de la requête, conforme à la référence API de ce point de terminaison

Chaque ligne doit être un JSON valide et autonome : pas de virgule de séparation, pas de crochet englobant. Les points de terminaison peuvent être mélangés dans le même fichier ; chaque requête est routée indépendamment.

Générer un fichier JSONL en Python

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... jusqu'à 50 000 documents par fichier
]

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")

Téléversement via l’API Files

Tu téléverses le fichier via le point de terminaison /v1/files, sans aucun autre paramètre :

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

Avec le SDK 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}")

Créer le lot à partir du fichier

Le fichier n’est pas ajouté à un lot existant : tu le spécifies au moment de la création avec 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}")

Le fichier est ensuite lu en arrière-plan. Si même une seule ligne est invalide, le lot est annulé avec un message d’erreur. Le suivi et la récupération des résultats fonctionnent ensuite exactement comme pour un lot soumis via l’API.

Limites du format JSONL

  • Maximum 50 000 requêtes par fichier
  • Maximum 200 Mo par fichier
  • Un custom_id unique par ligne
  • Un lot créé à partir d’un fichier est scellé : tu ne peux pas lui ajouter d’éléments ultérieurement via l’API

Si ton lot dépasse ces limites, divise-le en plusieurs fichiers et crée un lot par fichier. Il n’y a aucune limite au nombre de lots par équipe.

Générer un fichier 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");

Validation et débogage

Une seule ligne invalide annule tout le lot : valide le fichier avant de le téléverser. Un script simple couvre l’essentiel :

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")

Viktiga punkter

  • Le format JSONL contient un objet JSON par ligne : custom_id, method, url, body
  • Tu téléverses le fichier via /v1/files, puis tu le spécifies lors de la création du lot (input_file_id)
  • Maximum 50 000 requêtes et 200 Mo par fichier ; au-delà, un lot par fichier
  • Un lot créé à partir d’un fichier est scellé, et une seule ligne invalide l’annule entièrement
  • Valide le fichier avant de le téléverser