Ajouter des requêtes en JSON

Ajout requête par requête

Une fois le batch créé, vous devez y ajouter des requêtes. La première méthode consiste à envoyer chaque requête individuellement via POST /v1/batches/{batch_id}/requests. Cette approche convient aux petits volumes ou aux scénarios où vous construisez le lot de manière incrémentale.

Structure d’une requête

Chaque requête ajoutée au batch doit contenir quatre champs :

{
  "custom_id": "req-001",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "grok-4.5",
    "messages": [
      {"role": "system", "content": "Vous êtes un assistant spécialisé en resume."},
      {"role": "user", "content": "Résumez cet article en 3 phrases."}
    ]
  }
}

• custom_id : identifiant unique de votre choix. C’est votre clé de correspondance entre la requête soumise et le résultat. Utilisez un identifiant significatif (ID base de données, hash du document, etc.)
• method : toujours "POST" pour les endpoints de génération
• url : le chemin de l’endpoint cible (/v1/chat/completions, /v1/responses, etc.)
• body : le corps de la requête, identique à ce que vous enverriez en mode synchrone

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 '{
    "custom_id": "article-42",
    "method": "POST",
    "url": "/v1/chat/completions",
    "body": {
      "model": "grok-4.5",
      "messages": [
        {"role": "user", "content": "Classifie ce texte : positif, neutre ou négatif."}
      ]
    }
  }'

Ajout en boucle avec Python

Pour ajouter plusieurs requêtes en séquence :

import openai
import time

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

documents = [
    {"id": "doc-1", "text": "Premier document a analyser..."},
    {"id": "doc-2", "text": "Deuxieme document a analyser..."},
    {"id": "doc-3", "text": "Troisieme document a analyser..."},
]

batch_id = "batch_abc123"

for doc in documents:
    client.batches.requests.create(
        batch_id=batch_id,
        custom_id=doc["id"],
        method="POST",
        url="/v1/chat/completions",
        body={
            "model": "grok-4.5",
            "messages": [
                {"role": "user", "content": f"Resume ce document : {doc['text']}"}
            ]
        }
    )

Rate limits sur l’ajout

L’ajout de requêtes est soumis à une limite de 1 000 appels par 30 secondes (fenêtre glissante). Cela signifie que vous pouvez ajouter environ 33 requêtes par seconde de manière soutenue.

Pour les gros volumes (plus de quelques centaines de requêtes), la méthode JSON individuelle devient limitante. Au-delà de 1 000 requêtes, privilégiez la méthode JSONL présentée dans la leçon suivante : elle permet d’ajouter jusqu’à 50 000 requêtes en un seul appel.

Quand utiliser l’ajout JSON

L’ajout requête par requête convient chaque fois que la souplesse compte plus que le débit. Sur un lot de petite taille — moins d’une centaine de requêtes — le temps d’ajout individuel reste négligeable, et la simplicité du code l’emporte sur toute optimisation. Il devient même 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 ou un flux de données s’ajoutent une à une, là où un fichier JSONL supposerait de tout connaître d’avance. C’est aussi la voie du prototypage — tester le workflow complet avec cinq requêtes avant d’industrialiser — et celle des lots hétérogènes, où chaque requête a une structure différente qui se prête mal à la génération mécanique d’un fichier pré-assemblé.

Validation des requêtes

L’API valide chaque requête au moment de l’ajout. Si le format est invalide (champ manquant, endpoint inconnu, modèle inexistant), l’ajout échoue immédiatement avec un message d’erreur. C’est un avantage par rapport à la méthode JSONL ou les erreurs ne sont détectées qu’au moment du traitement.

Vérifiez systématiquement le code de retour HTTP de chaque ajout et implémentez une logique de gestion d’erreurs pour les requêtes rejetées.

Points clés à retenir

• L’ajout JSON envoie chaque requête individuellement via POST /v1/batches/{id}/requests
• Chaque requête nécessite un custom_id unique, un method, un url et un body
• La limite est de 1 000 ajouts par 30 secondes
• Pour les gros volumes, la méthode JSONL est plus efficace
• La validation est immédiate, ce qui facilite le débogage