Creer un batch vide

Premiere etape : l’initialisation

La creation d’un batch est la premiere action concrete de votre workflow. Un appel POST /v1/batches initialise un conteneur vide qui recevra ensuite vos requetes. Cette etape est volontairement minimale : elle cree l’identifiant et prepare l’infrastructure cote serveur.

L’appel de creation

L’appel est minimaliste. Aucun parametre obligatoire n’est requis dans le corps de la requete :

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

La reponse contient le batch_id et l’etat initial :

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

Implementation en Python

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

import openai

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

# Creer le batch vide
batch = client.batches.create()
batch_id = batch.id
print(f"Batch cree : {batch_id}")

Le batch_id retourne est la reference unique de votre lot. Conservez-le dans une variable, un fichier, ou une base de donnees selon votre architecture.

Implementation 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 a la creation

La creation de batchs est soumise a une limite de 2 creations par seconde par equipe. Dans la pratique, cette limite est rarement atteinte : vous creez generalement un seul batch par operation, puis vous y ajoutez toutes vos requetes.

Si vous automatisez la creation 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 metadonnees pour identifier vos batchs. Sinon, maintenez un mapping batch_id → description dans votre systeme.

Verifiez le statut initial : apres la creation, assurez-vous que le statut est bien pending avant de passer a l’etape suivante.

Gerez les erreurs de creation : une erreur d’authentification, un depassement de quota, ou un probleme reseau peuvent empecher la creation. Implementez une logique de retry avec backoff exponentiel.

Points cles a retenir

• La creation d’un batch est un simple POST /v1/batches sans parametres obligatoires
• La reponse contient un batch_id unique a conserver pour toute la suite du workflow
• La limite est de 2 creations par seconde par equipe
• Le batch est cree dans l’etat pending, pret a recevoir des requetes
• Implementez une gestion d’erreurs et un mecanisme de retry