Flux de travail asynchrone et interrogation
Šajā lapā
Mis à jour le 2 novembre 2026. Selon la référence de l’API vidéo xAI : l’URL se trouve dans
video.url(et nonvideo_url), une génération n’a que trois statuts (pending,done,failed, ce dernier étant accompagné d’un code d’erreur), et les limites de débit sont exprimées en requêtes par seconde selon le niveau de l’équipe. Sources : Génération vidéo · Référence Vidéos · Limites de débit.
Comprendre le cycle de vie d’une vidéo
Toutes les opérations vidéo de l’API xAI sont asynchrones, une caractéristique qui façonne l’architecture de ton application plus que tu ne pourrais le penser au premier abord. Un appel de chat ou une génération d’image renvoie un résultat immédiat ; la génération vidéo, en revanche, nécessite un temps de traitement important et ne retourne qu’un accusé de réception. C’est à toi de mettre en œuvre le suivi : interroger périodiquement le statut de la tâche, détecter son achèvement et récupérer le fichier. Le cycle complet comporte quatre étapes.
Soumettre la requête
POST vers le point de terminaison de génération, d'édition ou d'extension. Réponse immédiate avec un request_id.
Interroger le statut
GET /v1/videos/{request_id} à intervalles réguliers. Le champ progress passe de 0 à 100.
Récupérer le résultat
Lorsque le statut est done (progress = 100), l'URL de la vidéo est disponible.
Télécharger immédiatement
L'URL de la vidéo est temporaire. Télécharge-la dès que possible.
Vérifier le statut de génération
Le suivi implique une simple requête GET vers le point de terminaison de statut, en utilisant l’identifiant reçu lors de la soumission.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
La réponse expose les informations utiles suivantes :
- status : l’état actuel de la génération
- progress : un entier de 0 à 100 indiquant la progression
- video.url : l’URL de la vidéo, à l’intérieur de l’objet
videoprésent lorsque le statut estdone, avec sa durée (video.duration) - video.respect_moderation : un booléen indiquant si le contenu est conforme à la politique de modération
- error : en cas d’échec, un code (
invalid_argument,permission_denied,failed_precondition,service_unavailableouinternal_error) et un message - usage.cost_in_usd_ticks : le coût de la requête, en dix-milliardièmes de dollar
Le champ progress mérite une note : il ne pilote pas ta logique de contrôle, qui doit toujours reposer sur status, mais il est précieux pour une interface utilisateur. Afficher „62 %” plutôt qu’un spinner statique change complètement la perception d’une attente pouvant durer plusieurs minutes.
Trois états, trois actions
| Statut | Progression | Signification |
|---|---|---|
pending | 0-99 | Génération en cours |
done | 100 | Terminé, URL disponible |
failed | absent | Échec de la génération |
Tant que le statut est pending, la génération se poursuit : tu continues simplement d’interroger à intervalles réguliers, en relayant progress vers ton interface. Lorsqu’il passe à done, la vidéo est prête, et la seule chose à faire est de lire video.url et de télécharger le fichier immédiatement — ces URL sont temporaires et la documentation ne précise pas leur durée de vie, ce qui interdit de les stocker dans une base de données pour une utilisation ultérieure.
Enfin, le statut failed indique un échec de production, et le champ error t’indique lequel. La distinction est importante pour la suite : service_unavailable (service temporairement surchargé) ou internal_error justifient une nouvelle tentative plus tard, tandis que invalid_argument ou permission_denied — prompt rejeté, image ou vidéo source invalide — nécessitent de corriger la requête d’abord. Le SDK Python, pour sa part, signale également via une erreur une requête différée qui a expiré avant d’être récupérée.
Mettre en œuvre l’interrogation
La version synchrone tient en une seule fonction. Elle boucle jusqu’au délai d’attente, sort prématurément en cas d’échec en levant son code, et renvoie l’URL dès que la vidéo est prête.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Attendre l'achèvement de la génération vidéo."""
headers = {"Authorization": f"Bearer {api_key}"}
debut = time.time()
while time.time() - debut < timeout:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
status = resp.get("status")
progress = resp.get("progress", 0)
if status == "done":
return resp["video"]["url"]
elif status == "failed":
erreur = resp.get("error", {})
raise RuntimeError(f"Échec de la génération [{erreur.get('code')}] : {erreur.get('message')}")
print(f"En cours... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Délai d'attente dépassé après {timeout} secondes")
Dans un service gérant plusieurs requêtes simultanément, cette version bloquante devient un goulot d’étranglement : chaque attente immobilise un thread pendant des minutes. La transposition asynchrone libère la boucle d’événements entre les requêtes et te permet de suivre des dizaines de générations en parallèle.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Version asynchrone de l'interrogation."""
headers = {"Authorization": f"Bearer {api_key}"}
async with httpx.AsyncClient() as client:
debut = asyncio.get_event_loop().time()
while asyncio.get_event_loop().time() - debut < timeout:
resp = await client.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
)
data = resp.json()
if data["status"] == "done":
return data["video"]["url"]
elif data["status"] == "failed":
raise RuntimeError(f"Échec de la génération : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Délai d'attente dépassé")
Définir l’intervalle d’interrogation
Le choix de l’intervalle équilibre réactivité et gaspillage de requêtes. Cinq secondes constituent un bon compromis dans la plupart des cas. Pour les générations longues — dix à quinze secondes de vidéo — dix à quinze secondes entre les interrogations suffisent amplement et réduisent le trafic. À l’inverse, une application interactive où l’utilisateur observe une barre de progression justifie de descendre à deux ou trois secondes. En dessous d’une seconde, cependant, tu n’accéléreras rien : la génération progresse à son propre rythme, et tu ne feras que multiplier les requêtes pour rien.
Galvenās atziņas
- Toutes les opérations vidéo sont asynchrones : POST pour soumettre, GET pour récupérer
- Trois statuts possibles : pending, done, failed (avec un code d’erreur)
- Le champ
progress(0-100) te permet de suivre l’avancement - Mets en œuvre un délai d’attente et un intervalle d’interrogation adaptés à ton cas d’usage
- Les URL vidéo sont temporaires : télécharge-les immédiatement