Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Flux de travail asynchrone et interrogation

Nodarbība 10 no 12 Atjaunota 2026. gada 2. novembris Vidējs
Šajā lapā
  1. Comprendre le cycle de vie d’une vidéo
  2. Vérifier le statut de génération
  3. Trois états, trois actions
  4. Mettre en œuvre l’interrogation
  5. Définir l’intervalle d’interrogation
  6. Galvenās atziņas

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 non video_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.

1

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.

2

Interroger le statut

GET /v1/videos/{request_id} à intervalles réguliers. Le champ progress passe de 0 à 100.

3

Récupérer le résultat

Lorsque le statut est done (progress = 100), l'URL de la vidéo est disponible.

4

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 video présent lorsque le statut est done, 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_unavailable ou internal_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

StatutProgressionSignification
pending0-99Génération en cours
done100Terminé, URL disponible
failedabsentÉ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