Workflow en quatre étapes

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.

Le cycle de vie d’un batch

Chaque batch suit le même cycle : création, ajout de requêtes, traitement, récupération des résultats. Comprendre ce cycle est essentiel avant de passer à l’implémentation, car chaque étape a ses contraintes et ses bonnes pratiques.

Étape 1 : Créer un batch

Tout commence par un appel POST /v1/batches, avec un seul champ obligatoire : le nom du batch. L’API retourne un identifiant unique (batch_id) que vous utiliserez pour toutes les opérations suivantes.

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 aussi les dates de création et d’expiration du batch (create_time, expire_time) et un objet state dont tous les compteurs sont encore à zéro.

Étape 2 : Ajouter des requêtes

Deux méthodes existent :

Par l’API : vous envoyez des requêtes avec POST /v1/batches/{batch_id}/requests. Chaque appel transporte une liste de requêtes, et vous pouvez en ajouter tant que le batch n’est pas annulé. C’est la voie des lots construits au fil de l’eau.

Par un fichier JSONL : vous préparez un fichier contenant toutes vos requêtes, vous le téléversez par la Files API, puis vous créez le batch à partir de ce fichier. Le batch est alors scellé : plus aucun ajout n’est possible. C’est la voie des gros volumes préparés d’avance.

Chaque requête porte un identifiant unique dans le batch : batch_request_id dans l’API, custom_id dans le fichier JSONL. Si vous l’omettez dans l’API, xAI génère un UUID ; donnez plutôt le vôtre (un identifiant de base de données, par exemple) : il sert de clé de correspondance entre vos données et les résultats, et garantit qu’une requête n’est traitée qu’une fois.

Étape 3 : Surveiller la progression

Le traitement démarre dès que les requêtes arrivent ; il n’y a pas d’étape « lancer ». Pendant ce temps, GET /v1/batches/{batch_id} renvoie l’objet state et ses compteurs : num_requests (total), num_pending (en attente), num_success (réussies), num_error (en erreur) et num_cancelled (annulées).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Quand num_pending tombe à zéro, toutes les requêtes ont été traitées, avec succès ou non. Un polling périodique suffit : quelques secondes pour un petit lot de test, quelques minutes pour un gros lot.

Étape 4 : Récupérer les résultats

Les résultats se lisent avec GET /v1/batches/{batch_id}/results, sans attendre la fin du batch : chaque requête est disponible dès qu’elle est traitée. La réponse est paginée : limit fixe la taille de la page (1 000 au maximum) et le pagination_token renvoyé sert à demander la page suivante ; il est vide sur la dernière.

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Chaque résultat porte le batch_request_id de sa requête : vous reconstituez ainsi la correspondance entre vos données d’entrée et les réponses de Grok.

Le workflow dans la pratique

Dans un pipeline de production, le workflow se traduit généralement par deux processus distincts :

• Un processus de soumission qui crée le batch, prépare et ajoute les requêtes, puis enregistre le batch_id
• Un processus de récupération qui interroge périodiquement les compteurs et télécharge les résultats au fur et à mesure

Cette séparation permet d’intégrer la Batch API dans des architectures pilotées par événements ou des pipelines de données existants (tâches cron, Apache Airflow, files d’attente).

Gestion des erreurs dans le workflow

Un batch n’a pas d’état global « réussi » ou « échoué » : il se lit à ses compteurs. Une requête en erreur incrémente num_error et figure dans les résultats avec son message d’erreur, sans bloquer les autres. Vous devez donc examiner chaque résultat et traiter les échecs au cas par cas.

Deux événements touchent le batch entier. L’annulation, par vous ou par xAI, qui l’explique alors dans le champ cancel_by_xai_message — c’est notamment le cas quand une ligne d’un fichier JSONL est invalide. Et l’expiration (expire_time), après laquelle les résultats ne sont plus accessibles : récupérez-les sans tarder.

Points clés à retenir

• Le workflow suit l’ordre : créer (avec un nom), ajouter, surveiller, récupérer
• L’identifiant de requête (batch_request_id, ou custom_id en JSONL) est votre clé de correspondance
• La progression se lit dans les compteurs de state ; tout est traité quand num_pending vaut zéro
• Les résultats sont paginés (limit, pagination_token) et disponibles au fil de l’eau
• Les erreurs sont gérées requête par requête ; annulation et expiration concernent le batch entier