Créer un batch vide

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.

Première étape : l’initialisation

La création d’un batch est la première action concrète de votre workflow. Un appel POST /v1/batches initialise un conteneur vide, qui recevra ensuite vos requêtes. Cette étape est volontairement minimale : elle crée l’identifiant et prépare le lot côté serveur.

L’appel de création

Le corps de la requête ne contient qu’un champ obligatoire, name :

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "analyse_avis_clients"}'

La réponse contient le batch_id, les dates de création et d’expiration, et les compteurs du batch, encore à zéro (exemple de la référence de l’API) :

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "analyse_avis_clients",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Implémentation en Python

Le SDK officiel s’installe avec pip install xai-sdk (version 1.21.0 au 2 novembre 2026, Python 3.10 minimum). Il lit la clé dans la variable d’environnement XAI_API_KEY :

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="analyse_avis_clients")
batch_id = batch.batch_id
print(f"Batch créé : {batch_id}")

Le batch_id retourné est la référence unique de votre lot. Conservez-le dans une variable, un fichier ou une base de données selon votre architecture.

Implémentation en JavaScript

Sans SDK, un simple fetch vers l’API REST suffit :

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "analyse_avis_clients" })
});

const batch = await response.json();
console.log(`Batch créé : ${batch.batch_id}`);

Rate limits à la création

La création de batchs est limitée à 2 par seconde par équipe ; le nombre de batchs, lui, n’est pas plafonné. Dans la pratique, cette limite est rarement atteinte : vous créez généralement un seul batch par opération, puis vous y ajoutez toutes vos requêtes. Si vous en créez plusieurs dans une boucle, espacez les appels d’au moins 500 millisecondes.

Bonnes pratiques

Nommez vos batchs avec soin : le nom est obligatoire, autant qu’il serve. Un nom qui dit le jeu de données et la date (avis_clients_2026_11_02) se retrouve facilement dans la liste des batchs et dans la console xAI, qui permet aussi de suivre les lots visuellement.

Notez l’expiration : expire_time indique quand le batch et ses résultats cessent d’être accessibles. Votre processus de récupération doit passer avant.

Gérez les erreurs de création : une erreur d’authentification, un dépassement de limite ou un incident réseau peuvent empêcher la création. Réessayez les erreurs transitoires avec un délai croissant (backoff exponentiel), jamais les erreurs d’authentification.

Points clés à retenir

• La création d’un batch est un POST /v1/batches dont le seul champ obligatoire est name
• La réponse contient un batch_id unique à conserver pour toute la suite du workflow
• En Python, le SDK officiel xai-sdk expose client.batch.create(batch_name=...)
• La limite est de 2 créations par seconde par équipe, sans plafond sur le nombre de batchs
• Surveillez expire_time et réessayez les seules erreurs transitoires