Gestion des erreurs et déploiement en production
Pe această pagină
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), le résultat se trouve dansurl, les échecs sont signalés parVideoGenerationErroravec un code (invalid_argument,service_unavailable…), la limite de débit est 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é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 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) | Mettre en œuvre 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 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.