Workflow asynchrone et polling

Comprendre le cycle de vie d’une video

Toutes les operations video de l’API xAI sont asynchrones. Contrairement aux appels de chat ou de generation d’images qui retournent un resultat immediatement, la generation video necessite un temps de traitement significatif. Vous devez donc implementer un mecanisme de polling pour suivre l’avancement et recuperer le resultat.

L’endpoint GET /v1/videos/{request_id}

Pour verifier l’avancement d’une generation, effectuez un GET sur l’endpoint de statut :

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Champs de la reponse

La reponse contient les informations suivantes :

• status : l’etat courant de la generation
• progress : un entier de 0 a 100 indiquant l’avancement
• video_url : l’URL de la video (uniquement quand le statut est done)
• video.respect_moderation : un booleen indiquant si le contenu respecte la politique de moderation

Les quatre statuts

Statut pending

La generation est en cours. Le champ progress vous donne une indication de l’avancement. Continuez a interroger le statut a intervalles reguliers.

Statut done

La video est prete. Recuperez l’URL dans le champ video_url et telechargez-la immediatement. Les URLs sont temporaires et expirent apres un delai non specifie.

Statut expired

Le resultat a expire avant que vous ne le recuperiez. Relancez la generation.

Statut failed

La generation a echoue. Les causes possibles incluent un prompt non conforme a la politique de contenu, un probleme technique, ou une image/video source invalide.

Implementation du polling

Version basique en Python

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Attend la completion d'une generation video."""
    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":
            raise Exception("Generation echouee")
        elif status == "expired":
            raise Exception("Generation expiree")

        print(f"En cours... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Timeout apres {timeout} secondes")

Version asynchrone

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Version asynchrone du polling."""
    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"] in ("failed", "expired"):
                raise Exception(f"Statut : {data['status']}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Timeout")

Choix de l’intervalle de polling

• 5 secondes : bon compromis pour la plupart des cas
• 10-15 secondes : pour les generations longues (10-15 secondes de video)
• 2-3 secondes : pour les applications interactives ou le feedback utilisateur est important

Evitez de descendre sous 1 seconde : cela ne accelere pas la generation et peut contribuer a atteindre la limite de debit.

Points cles a retenir

• Toutes les operations video sont asynchrones : POST pour soumettre, GET pour recuperer
• Quatre statuts possibles : pending, done, expired, failed
• Le champ progress (0-100) permet de suivre l’avancement
• Implementez un timeout et un intervalle de polling adapte a votre cas d’usage
• Les URLs de video sont temporaires : telechargez immediatement