SDK xAI et polling automatique

Simplifier le polling avec les SDK

La gestion manuelle du polling est fonctionnelle mais verbeuse. Les SDK officiels de xAI simplifient considerablement le processus en gerant automatiquement l’interrogation du statut et le retour du resultat. Dans cette lecon, vous allez decouvrir comment utiliser le SDK Python pour la generation video.

Polling automatique du SDK

Le SDK xAI encapsule tout le mecanisme de polling dans un appel unique. Vous soumettez la requete et recevez directement le resultat une fois la generation terminee :

from xai_sdk import Client

client = Client(api_key="votre_cle")

# Generation text-to-video avec polling automatique
result = await client.videos.generate(
    model="grok-imagine-video",
    prompt="Un lever de soleil sur les Alpes, time-lapse accelere",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p"
)

print(result.video_url)

Le SDK gere en interne :

• L’envoi de la requete POST
• Le polling a intervalles reguliers (~100ms par defaut)
• La detection du statut final (done, failed, expired)
• Le retour du resultat ou la levee d’une exception

Configuration du timeout

Par defaut, le SDK attend jusqu’a 10 minutes avant de lever une exception de timeout. Vous pouvez ajuster cette valeur :

result = await client.videos.generate(
    model="grok-imagine-video",
    prompt="Votre description",
    duration=10,
    timeout=300  # 5 minutes max
)

Gestion d’erreurs avec le SDK

Le SDK fournit des exceptions specifiques pour chaque type d’erreur :

from xai_sdk.exceptions import VideoGenerationError, TimeoutError

try:
    result = await client.videos.generate(
        model="grok-imagine-video",
        prompt="Votre description",
        duration=5
    )
    print(f"Video prete : {result.video_url}")
except VideoGenerationError as e:
    print(f"Erreur de generation - Code: {e.code}, Message: {e.message}")
except TimeoutError:
    print("La generation a pris trop de temps")
except Exception as e:
    print(f"Erreur inattendue : {e}")

Types d’erreurs courantes

Edition et extension avec le SDK

Le SDK propose des methodes dediees pour l’edition et l’extension :

Edition

result = await client.videos.edit(
    model="grok-imagine-video",
    prompt="Transforme en style anime japonais",
    video_url="https://exemple.com/video.mp4"
)

Extension

result = await client.videos.extend(
    model="grok-imagine-video",
    prompt="Continue la scene avec un panoramique vers la droite",
    video_url="https://exemple.com/video.mp4",
    duration=5
)

Telechargement automatique

Les URLs de video generees sont temporaires. Implementez un telechargement systematique :

import httpx
from pathlib import Path

async def generer_et_sauvegarder(client, prompt, fichier_sortie, **kwargs):
    """Genere une video et la sauvegarde localement."""
    result = await client.videos.generate(
        model="grok-imagine-video",
        prompt=prompt,
        **kwargs
    )

    # Telechargement immediat
    async with httpx.AsyncClient() as http:
        resp = await http.get(result.video_url)
        Path(fichier_sortie).write_bytes(resp.content)

    print(f"Video sauvegardee : {fichier_sortie}")
    return fichier_sortie

Batch de generations

Pour generer plusieurs videos en parallele avec le SDK :

import asyncio

async def batch_generation(client, requetes):
    """Genere plusieurs videos en parallele."""
    taches = []
    for req in requetes:
        tache = client.videos.generate(
            model="grok-imagine-video",
            prompt=req["prompt"],
            duration=req.get("duration", 5),
            aspect_ratio=req.get("aspect_ratio", "16:9")
        )
        taches.append(tache)

    resultats = await asyncio.gather(*taches, return_exceptions=True)

    for i, res in enumerate(resultats):
        if isinstance(res, Exception):
            print(f"Requete {i+1} echouee : {res}")
        else:
            print(f"Requete {i+1} terminee : {res.video_url}")

    return resultats

Limites du parallelisme

• Respectez la limite de 60 RPM
• Lancez au maximum 10-15 generations simultanees
• Le parallelisme n’accelere pas les generations individuelles, mais reduit le temps total du batch

Comparaison : polling manuel vs SDK

Le polling manuel reste utile si vous avez besoin d’un controle fin (affichage de progression, integration specifique) ou si vous ne pouvez pas ajouter la dependance au SDK.

Points cles a retenir

• Le SDK gere automatiquement le polling avec un timeout de 10 minutes par defaut
• Les exceptions specifiques facilitent le traitement des erreurs
• Telechargez toujours la video immediatement apres la generation (URLs temporaires)
• Le parallelisme via asyncio.gather accelere les batches de generations
• Le polling manuel reste pertinent pour des besoins de controle avances