Salt la conținutul principal
Română— Alege o limbă
Meniu

Gestion des erreurs et déploiement en production

Lecția 12 din 12 Actualizată 3 noiembrie 2026 Intermediar
Pe această pagină
  1. Préparez votre application pour la production
  2. Deux familles d’erreurs, deux moments
  3. Réessayer intelligemment
  4. Une file d’attente pour garder le rythme
  5. Vérifiez votre clé avant de dépendre d’elle
  6. Voyez ce qui se passe en production
  7. Puncte cheie
  8. Testez vos connaissances

Mis à jour le 2 novembre 2026 sur la base de la documentation vidéo de xAI et du code xai-sdk 1.21.0 : client.video.generate (et non client.videos), le résultat se trouve dans url, les échecs sont signalés par VideoGenerationError avec un code (invalid_argument, service_unavailable…), la limite de débit est reçue sous forme de grpc.RpcError avec le code RESOURCE_EXHAUSTED — la classe RateLimitError et le statut expired n’existent pas. Complément du 3 novembre 2026 : la limite de débit compte les requêtes par seconde (10 pour le niveau d’entrée), et non « 60 RPM », et le coût réel par génération est lu dans usage.cost_in_usd_ticks. Sources : Génération vidéo · Limites de débit.

Préparez votre application pour la production

Un script qui génère une vidéo sur votre machine et un service qui en produit des centaines par jour pour de vrais utilisateurs n’ont presque rien en commun. Ce dernier doit gérer les refus de modération, les dépassements de quota, les incidents serveur et l’expiration des URL sans jamais perdre silencieusement une génération facturée. Cette leçon couvre les mécanismes qui font la différence : classification des erreurs, stratégie de nouvelle tentative, architecture de file d’attente et observabilité.

Deux familles d’erreurs, deux moments

La première famille apparaît immédiatement, au moment de l’appel POST. Il s’agit d’erreurs de requête strictes, et le code HTTP suffit à décider de la marche à suivre.

Code HTTPCauseSolution
400Paramètres invalides (par exemple, une voix inconnue dans reference_audios)Corriger la requête
401Clé API invalide ou expiréeVérifier l’authentification
429Limite de débit dépassée (requêtes par seconde, selon le niveau)Mettre en œuvre un backoff
500Erreur serveurRéessayer avec un backoff exponentiel

La seconde famille se manifeste beaucoup plus tard, lors du sondage (polling), après que la requête a été acceptée et que la génération a commencé.

StatutCause probableAction
failed + invalid_argument ou permission_deniedRequête ou contenu refuséModifier le prompt ou la source
failed + service_unavailable ou internal_errorService surchargé, incidentRéessayer plus tard

Cette distinction n’est pas académique : un 400 doit retourner instantanément à l’appelant car le code est en faute, tandis qu’un statut failed survient après plusieurs minutes d’attente et doit être géré dans le contexte de la tâche (job), et non dans la requête HTTP qui l’a déclenchée.

Réessayer intelligemment

La base commune est le backoff exponentiel avec un peu de gigue (jitter). Doubler le délai laisse le temps à un incident transitoire de se résoudre, et la gigue empêche tous vos processus de réessayer au même instant après un pic — un phénomène qui transforme une micro-panne en échec durable.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Exécute une fonction avec nouvelle tentative et backoff exponentiel."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Backoff exponentiel avec gigue
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Tentative {attempt + 1} échouée : {e}. Nouvelle tentative dans {delay:.1f}s")
            await asyncio.sleep(delay)

Ce schéma générique ne suffit cependant pas, car toutes les erreurs ne méritent pas la même patience. Un dépassement de quota se résout en attendant une minute entière ; un refus de modération ne se résoudra jamais, et réessayer revient à payer plusieurs fois pour le même échec. La fonction suivante différencie les cas.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Codes d'échec qu'une nouvelle tentative ne corrigera pas
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Génération vidéo avec nouvelle tentative ciblée (client : xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # requête ou contenu refusé : corriger avant de relancer
            await asyncio.sleep(5 * (attempt + 1))  # service surchargé, incident
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # limite de débit : backoff
        except TimeoutError:
            if is_last:
                raise
            # Accorder plus de temps pour la prochaine tentative
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Une file d’attente pour garder le rythme

Dès que votre service reçoit des requêtes de plusieurs utilisateurs, vous devez découpler la réception des requêtes de leur exécution, et surtout borner la concurrence pour rester sous la limite de débit de votre niveau. Une file d’attente couplée à un sémaphore répond à ces deux besoins : les tâches s’empilent librement, mais dix maximum s’exécutent à la fois.

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Ajoute une génération à la file d'attente."""
        self.queue.append((job_id, params))

    async def process(self):
        """Traite toutes les générations en attente."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Exécute une génération avec contrôle de la concurrence."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

Notez que chaque tâche conserve son résultat dans results, succès ou échec : une génération qui disparaît sans laisser de trace est un incident que personne ne peut diagnostiquer.

Le second réflexe d’architecture concerne le stockage. Puisque les URL vidéo sont temporaires, le téléchargement doit être automatique et immédiat, avec un nommage horodaté qui garantit l’absence de collision entre deux générations simultanées.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Télécharge et enregistre une vidéo générée."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Vérifiez votre clé avant de dépendre d’elle

Le point de terminaison GET /v1/api-key vous informe sur l’état de votre clé. L’appeler au démarrage du service évite de découvrir une clé bloquée après vingt requêtes échouées, pendant que vos utilisateurs attendent.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("Clé API ou équipe bloquée, ou clé désactivée")

Voyez ce qui se passe en production

Cinq indicateurs suffisent à piloter un service de génération vidéo. Le taux de réussite, c’est-à-dire la part des générations se terminant par done, mesure la santé globale. Le temps moyen de génération, mesuré entre la soumission et le statut done, sert à calibrer vos délais d’attente et à informer vos utilisateurs. Le taux d’erreur ventilé par type — failed par code d’erreur, timeout, limite de débit — vous indique où concentrer vos efforts : une hausse des timeouts sans hausse des failed signale par exemple des générations plus lentes que votre délai d’attente, et non des échecs. Le coût cumulatif, obtenu en sommant le champ usage.cost_in_usd_ticks de chaque résultat (un dollar équivaut à 10 milliards de ticks), ou alternativement en multipliant les durées générées par le prix par seconde du modèle, doit être surveillé quotidiennement. Enfin, l’utilisation du quota, en requêtes par seconde par rapport à la limite de votre niveau (10 au niveau d’entrée pour les modèles vidéo), anticipe la saturation avant qu’elle ne se traduise par des 429.

Ces métriques se construisent naturellement à partir d’un journal structuré, où chaque génération laisse une ligne exploitable par votre outil d’analyse.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

Avant d’ouvrir votre service au public, revoyez l’ensemble depuis le début. La nouvelle tentative avec backoff exponentiel et gigue doit être en place, et la concurrence bornée par un sémaphore pour rester sous la limite de débit. Les téléchargements vidéo doivent se déclencher automatiquement dès qu’ils sont prêts, sans dépendre d’une action humaine. Chaque génération doit laisser une ligne de journal portant son request_id, son statut et son coût, sinon le taux d’erreur et le temps moyen de génération resteront invérifiables. Vérifiez l’état de la clé API au démarrage plutôt qu’au premier échec. Et fixez un budget avec des alertes de dépassement : à 0,05 $ par seconde, une boucle de nouvelle tentative illimitée consomme plus vite que vous ne le pensez.

Tarification vérifiée le 3 novembre 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille actuelle sur la page officielle des modèles et tarifs xAI.

Puncte cheie

  • Les erreurs se divisent en synchrones (requête) et asynchrones (génération)
  • Toutes les erreurs ne méritent pas une nouvelle tentative : la modération est définitive
  • Utilisez un sémaphore pour limiter les générations concurrentes
  • Les URL temporaires nécessitent un téléchargement immédiat et systématique
  • Suivez les métriques de coût, de réussite et de temps de génération pour piloter votre service

Testez vos connaissances

Vidéo générative en production : validez le flux de travail complet.

1. Quelles sont les particularités d'un prompt vidéo ?

Réponse : Décrivez l’action et le mouvement, pas seulement la scène : sujet, déplacement, ambiance, cadrage — la dimension temporelle est ce qui distingue le prompt vidéo du prompt image.

2. Que permet l'image-vers-vidéo ?

Réponse : Animer une image existante, ou intégrer des personnes et des produits donnés dans une nouvelle scène en utilisant des images de référence — et, sur grok-imagine-video-1.5, épingler la première, la dernière ou les images clés : votre identité visuelle devient un point de départ, non un hasard.

3. Édition et extension : quels usages ?

Réponse : /videos/edits modifie une vidéo générée, /videos/extensions la prolonge — et les deux se combinent pour construire de longues séquences par itérations.

4. Pourquoi le flux de travail est-il asynchrone ?

Réponse : La génération vidéo prend du temps : vous soumettez une tâche, vous sondez son statut, puis vous récupérez le résultat — le SDK xAI automatise ce sondage.

5. Que prévoir pour la production ?

Réponse : La gestion des erreurs et des tâches échouées, le téléchargement immédiat des sorties, et le suivi des coûts (résolution, durée, itérations) — la vidéo est la modalité la plus coûteuse : elle doit être budgétisée.

Prompt temporel, référence visuelle, asynchrone maîtrisé : la vidéo générative devient un pipeline — et non une loterie.