Créer un batch vide

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 l’infrastructure côté serveur.

L’appel de création

L’appel est minimaliste. Aucun paramètre obligatoire n’est requis dans le corps de la requête :

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

La réponse contient le batch_id et l’état initial :

{
  "id": "batch_abc123",
  "status": "pending",
  "created_at": "2026-04-03T10:00:00Z"
}

Implémentation en Python

Avec le SDK xAI ou le SDK OpenAI (compatible), la création est tout aussi directe :

import openai

client = openai.OpenAI(
    api_key="votre-cle-xai",
    base_url="https://api.x.ai/v1"
)

# Créer le batch vide
batch = client.batches.create()
batch_id = batch.id
print(f"Batch cree : {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

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

const batch = await response.json();
console.log(`Batch cree : ${batch.id}`);

Rate limits à la création

La création de batchs est soumise à une limite de 2 créations par seconde par équipe. 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 automatisez la création de multiples batchs dans une boucle, espacez vos appels d’au moins 500 millisecondes pour rester dans les limites.

Bonnes pratiques

Nommez vos batchs : si l’API le permet, ajoutez des métadonnées pour identifier vos batchs. Sinon, maintenez un mapping batch_id → description dans votre système.

Vérifiez le statut initial : après la création, assurez-vous que le statut est bien pending avant de passer à l’étape suivante.

Gérez les erreurs de création : une erreur d’authentification, un dépassement de quota, ou un problème réseau peuvent empêcher la création. Implémentez une logique de retry avec backoff exponentiel.

Points clés à retenir

• La création d’un batch est un simple POST /v1/batches sans paramètres obligatoires
• La réponse contient un batch_id unique à conserver pour toute la suite du workflow
• La limite est de 2 créations par seconde par équipe
• Le batch est créé dans l’état pending, prêt à recevoir des requêtes
• Implémentez une gestion d’erreurs et un mécanisme de retry