Générer des vidéos par API REST : ce qu’il faut regarder
Beaucoup d’outils vidéo affichent « API disponible ». Entre un endpoint qui accepte un prompt et une API réellement intégrable dans un système de production, l’écart tient à cinq détails.
Synchrone ou asynchrone : ce n’est pas un détail
Un rendu vidéo prend rarement moins d’une minute. Une API purement synchrone impose donc de maintenir une connexion HTTP ouverte pendant toute la durée du rendu, ce qui entre en conflit avec presque tous les timeouts par défaut : proxies, passerelles, workers d’automatisation.
Une API utilisable en production propose les deux modes : synchrone pour les opérations courtes — une image, un recadrage, un sous-titrage — et asynchrone avec webhook pour tout ce qui implique un rendu vidéo complet.
Le contexte de marque doit être persistant
Le point le plus sous-estimé. Si chaque appel doit transporter le logo, la palette, la typographie, les personnages et les références produit, vos payloads deviennent énormes et vos résultats dérivent dès qu’un champ est oublié.
La bonne architecture stocke ce contexte côté serveur et l’adresse par identifiant. L’appel se réduit alors à un objectif et une référence de marque, et deux productions lancées à trois mois d’écart restent visuellement cohérentes.
Erreurs typées et idempotence
Deux propriétés font la différence entre une intégration qui tient et une intégration qu’il faut surveiller manuellement :
- Des erreurs typées. « Crédits insuffisants », « format non supporté » et « échec de rendu » appellent trois réactions différentes. Un message texte générique force à parser de la prose pour décider quoi faire.
- L’idempotence. Un rejeu de requête après timeout réseau ne doit pas produire — ni facturer — deux vidéos.
- Un statut interrogeable. Pouvoir demander l’état d’une production à tout moment évite de dépendre uniquement de la réception du webhook.
Comprendre le modèle de facturation avant d’industrialiser
Les API vidéo facturent rarement à la requête. Le modèle courant est le crédit, consommé différemment selon l’opération : une image coûte moins qu’un rendu vidéo complet, une voix clonée plus qu’une voix standard.
Chez Viffly, un crédit correspond à une action de génération, et un Reel classique en consomme plusieurs selon les étapes activées. Avant d’automatiser un volume, mesurez le coût réel d’une production complète sur quelques exécutions plutôt que d’extrapoler depuis le prix unitaire affiché.