Ajouter des requêtes en JSON

Cours révisé le 2 novembre 2026 d’après la documentation de xAI : la remise batch est de 20 % sur les modèles 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’a pas le format de celle d’OpenAI, le SDK OpenAI ne s’y applique pas), et l’API Responses passe avant Chat Completions, endpoint hérité chez xAI. Sources : Batch API · Référence REST · Tarifs batch.

Ajout par l’API

Une fois le batch créé, vous y ajoutez des requêtes avec POST /v1/batches/{batch_id}/requests. Chaque appel transporte une liste de requêtes, et vous pouvez appeler l’endpoint autant de fois que nécessaire tant que le batch n’est pas annulé. Cette approche convient aux lots construits de manière incrémentale.

Structure d’une requête

Le corps de l’appel contient un tableau batch_requests. Chaque élément associe un identifiant (batch_request_id) et la requête elle-même, rangée sous la clé de son type — responses pour l’API Responses :

{
  "batch_requests": [
    {
      "batch_request_id": "avis-001",
      "batch_request": {
        "responses": {
          "model": "grok-4.3",
          "input": [
            {"role": "system", "content": "Classe le sentiment : positif, négatif ou neutre."},
            {"role": "user", "content": "Le produit a dépassé mes attentes !"}
          ]
        }
      }
    }
  ]
}

• batch_request_id : votre identifiant, unique dans le batch. C’est la clé de correspondance entre la requête et son résultat ; s’il manque, xAI génère un UUID
• batch_request : la requête, sous la clé de son type ; la référence de l’API documente aussi chat_get_completion pour le format Chat Completions

Pour les images et les vidéos, passez par le SDK (leçon 9) ou par un fichier JSONL (leçon suivante).

Appel cURL

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_requests": [
      {
        "batch_request_id": "article-42",
        "batch_request": {
          "responses": {
            "model": "grok-4.3",
            "input": [
              {"role": "user", "content": "Classe ce texte : positif, neutre ou négatif."}
            ]
          }
        }
      }
    ]
  }'

Ajout avec le SDK Python

Avec le SDK, chaque requête se construit comme une conversation ordinaire, à qui l’on donne un batch_request_id ; on les ajoute ensuite par paquets :

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()

documents = [
    {"id": "doc-1", "text": "Premier document à analyser..."},
    {"id": "doc-2", "text": "Deuxième document à analyser..."},
    {"id": "doc-3", "text": "Troisième document à analyser..."},
]

batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"

requetes = []
for doc in documents:
    chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
    chat.append(system("Résume le document en deux phrases."))
    chat.append(user(doc["text"]))
    requetes.append(chat)

# Ajout par paquets de 100 : un appel d'API par paquet
for i in range(0, len(requetes), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requetes[i:i + 100])

La documentation ne fixe pas de nombre maximal de requêtes par appel ; des paquets de taille modérée limitent simplement ce qu’il faut renvoyer en cas d’incident réseau.

Rate limits sur l’ajout

Une équipe peut passer jusqu’à 1 000 appels d’ajout toutes les 30 secondes, en fenêtre glissante partagée entre tous ses batchs. La limite porte sur les appels, pas sur les requêtes : avec des paquets de 100 requêtes, elle autorise déjà plus de 3 000 requêtes par seconde. Deux autres bornes comptent davantage :

• 25 MB au maximum par requête individuelle, ce qui concerne surtout les images encodées en base64
• au-delà de 100 000 requêtes dans un batch, xAI peut ralentir le traitement pour préserver la stabilité du service

Quand utiliser l’ajout par l’API

L’ajout par l’API convient chaque fois que la souplesse compte plus que la préparation. Il devient le seul choix naturel quand le lot se construit incrémentalement : des requêtes qui arrivent au fil de l’eau depuis une file d’attente s’ajoutent à mesure, là où un fichier JSONL supposerait de tout connaître d’avance — et scellerait le batch. C’est aussi la voie du prototypage, pour tester le workflow complet avec cinq requêtes avant d’industrialiser, et celle des lots hétérogènes.

Validation des requêtes

Vérifiez le code de retour de chaque appel d’ajout : une erreur à ce stade signifie que le paquet n’a pas été enregistré, et qu’il faut le renvoyer. Une requête peut aussi échouer plus tard, au traitement ; elle apparaît alors dans les résultats avec son message d’erreur. Un modèle qui n’accepte pas le batch est rejeté avec le message not supported for batch processing : vérifiez l’éligibilité sur la page du modèle avant de lancer un gros lot.

Points clés à retenir

• L’ajout passe par POST /v1/batches/{id}/requests, avec une liste batch_requests
• Chaque requête porte un batch_request_id unique et son contenu sous la clé de son type (responses, chat_get_completion)
• Le SDK construit les requêtes avec client.chat.create(..., batch_request_id=...) et les ajoute avec client.batch.add
• La limite est de 1 000 appels d’ajout par 30 secondes pour l’équipe, chaque appel pouvant porter de nombreuses requêtes
• Contrairement au fichier JSONL, l’ajout par l’API laisse le batch ouvert à de nouveaux ajouts