Gestion des erreurs et déploiement en production
Šiame puslapyje
Mis à jour le 2 novembre 2026 sur la base de la documentation vidéo de xAI et du code
xai-sdk1.21.0 :client.video.generate(et nonclient.videos), résultat dansurl, échecs signalés parVideoGenerationErroravec un code (invalid_argument,service_unavailable…), limite de débit reçue sous forme degrpc.RpcErroravec le codeRESOURCE_EXHAUSTED— la classeRateLimitErroret le statutexpiredn’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 dansusage.cost_in_usd_ticks. Sources : Génération vidéo · Limites de débit.
Prépare ton application pour la production
Un script qui génère une vidéo sur ta 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. Ce sont des erreurs de requête strictes, et le code HTTP suffit à décider quoi faire.
| Code HTTP | Cause | Solution |
|---|---|---|
| 400 | Paramètres invalides (par exemple, une voix inconnue dans reference_audios) | Corriger la requête |
| 401 | Clé API invalide ou expirée | Vérifier l’authentification |
| 429 | Limite de débit dépassée (requêtes par seconde, selon le niveau) | Implémenter un backoff |
| 500 | Erreur serveur | Ré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é.
| Statut | Cause probable | Action |
|---|---|---|
failed + invalid_argument ou permission_denied | Requête ou contenu refusé | Modifier le prompt ou la source |
failed + service_unavailable ou internal_error | Service surchargé, incident | Réessayer plus tard |
Cette distinction n’est pas académique : un 400 doit revenir 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 jitter (aléatoire). Doubler le délai laisse le temps à un incident transitoire de se résoudre, et le jitter empêche tous tes 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 jitter
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 ton service reçoit des requêtes de plusieurs utilisateurs, tu dois 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 ton 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)
}
Note 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érifie ta clé avant de dépendre d’elle
Le point de terminaison GET /v1/api-key t’informe de l’état de ta 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 tes 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")
Vois 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 tes délais d’attente et à informer tes utilisateurs. Le taux d’erreur ventilé par type — failed par code d’erreur, timeout, limite de débit — t’indique où concentrer tes efforts : une hausse des timeouts sans hausse des failed signale des générations plus lentes que ton délai d’attente, par exemple, et non des échecs. Le coût cumulé, 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 ton niveau (10 pour le 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 ton 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 ton service au public, revois l’ensemble depuis le début. Le backoff exponentiel avec jitter 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érifie l’état de la clé API au démarrage plutôt qu’au premier échec. Et fixe un budget avec des alertes de dépassement : à 0,05 $ par seconde, une boucle de nouvelle tentative illimitée consomme plus vite que tu ne le penses.
Tarification vérifiée le 3 novembre 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifie la grille actuelle sur la page officielle des modèles et tarifs xAI.
Svarbiausi punktai
- 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
- Utilise un sémaphore pour limiter les générations concurrentes
- Les URL temporaires nécessitent un téléchargement immédiat et systématique
- Suis les métriques de coût, de réussite et de temps de génération pour piloter ton service
Teste tes connaissances
Vidéo générative en production : valide le flux de travail complet.
1. Quelles sont les particularités d'un prompt vidéo ?
Réponse : Décris 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 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 des images clés : ton identité visuelle devient un point de départ, pas 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 : tu soumets une tâche, tu sondes son statut, puis tu récupères 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 chère : elle doit être budgétisée.
Prompt temporel, référence visuelle, asynchrone maîtrisé : la vidéo générative devient un pipeline — pas une loterie.