Ajouter des requetes en JSON

Ajout requete par requete

Une fois le batch cree, vous devez y ajouter des requetes. La premiere methode consiste a envoyer chaque requete individuellement via POST /v1/batches/{batch_id}/requests. Cette approche convient aux petits volumes ou aux scenarios ou vous construisez le lot de maniere incrementale.

Structure d’une requete

Chaque requete ajoutee au batch doit contenir quatre champs :

{
  "custom_id": "req-001",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "grok-3",
    "messages": [
      {"role": "system", "content": "Vous etes un assistant specialise en resume."},
      {"role": "user", "content": "Resumez cet article en 3 phrases."}
    ]
  }
}

• custom_id : identifiant unique de votre choix. C’est votre cle de correspondance entre la requete soumise et le resultat. Utilisez un identifiant significatif (ID base de donnees, hash du document, etc.)
• method : toujours "POST" pour les endpoints de generation
• url : le chemin de l’endpoint cible (/v1/chat/completions, /v1/responses, etc.)
• body : le corps de la requete, identique a 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-3",
      "messages": [
        {"role": "user", "content": "Classifie ce texte : positif, neutre ou negatif."}
      ]
    }
  }'

Ajout en boucle avec Python

Pour ajouter plusieurs requetes en sequence :

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-3",
            "messages": [
                {"role": "user", "content": f"Resume ce document : {doc['text']}"}
            ]
        }
    )

Rate limits sur l’ajout

L’ajout de requetes est soumis a une limite de 1 000 appels par 30 secondes (fenetre glissante). Cela signifie que vous pouvez ajouter environ 33 requetes par seconde de maniere soutenue.

Pour les gros volumes (plus de quelques centaines de requetes), la methode JSON individuelle devient limitante. Au-dela de 1 000 requetes, privilegiez la methode JSONL presentee dans la lecon suivante : elle permet d’ajouter jusqu’a 50 000 requetes en un seul appel.

Quand utiliser l’ajout JSON

L’ajout requete par requete est adapte dans ces situations :

• Lots de petite taille : moins de 100 requetes, ou le temps d’ajout reste negligeable
• Construction incrementale : vous ajoutez des requetes au fur et a mesure qu’elles arrivent (file d’attente, stream de donnees)
• Prototypage : vous testez le workflow avec quelques requetes avant de passer a l’echelle
• Requetes heterogenes : chaque requete a une structure differente et ne se prete pas bien a un fichier JSONL pre-genere

Validation des requetes

L’API valide chaque requete au moment de l’ajout. Si le format est invalide (champ manquant, endpoint inconnu, modele inexistant), l’ajout echoue immediatement avec un message d’erreur. C’est un avantage par rapport a la methode JSONL ou les erreurs ne sont detectees qu’au moment du traitement.

Verifiez systematiquement le code de retour HTTP de chaque ajout et implementez une logique de gestion d’erreurs pour les requetes rejetees.

Points cles a retenir

• L’ajout JSON envoie chaque requete individuellement via POST /v1/batches/{id}/requests
• Chaque requete necessite 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 methode JSONL est plus efficace
• La validation est immediate, ce qui facilite le debogage