API vidéo OpenRouter : un endpoint pour Seedance, Veo et Wan

Un endpoint, plusieurs modèles : ce que propose OpenRouter

OpenRouter vient de publier un guide développeur pour son API de génération vidéo. Le principe : un endpoint unique — POST /api/v1/videos — qui donne accès à plusieurs modèles, dont Seedance, Veo et Wan. L'authentification repose sur un bearer tokenUnité de texte traitée par un modèle (souvent un morceau de mot). Les coûts et fenêtres de contexte se comptent en tokens. classique, et une requête réussie retourne un code HTTP 202 Accepted. Pour le pendant image de cette API, voir notre article sur l'API de génération d'images d'OpenRouter.

La génération vidéo pouvant prendre de plusieurs secondes à quelques minutes selon le modèle et les paramètres demandés, OpenRouter a opté pour une architecture asynchrone : nous soumettons un promptConsigne / contexte fourni au modèle pour orienter sa génération (system, user, exemples, outils)., recevons immédiatement un job ID, puis interrogeons le statut du job séparément avant de télécharger la vidéo terminée. Les statuts documentés sont pending, in_progress, completed, failed, cancelled et expired.

Point important : tous les modèles ne supportent pas les mêmes paramètres. Les réglages optionnels — durée, résolution, ratio d'aspect, génération audio, images de référence, seed — dépendent du modèle sélectionné. Un endpoint dédié (/api/v1/videos/models) permet de consulter les modèles disponibles et leurs capacités respectives avant de soumettre un job.

L'exemple fourni par OpenRouter rend cette différence de capacités concrète : une configuration de 4 secondes en 720p et 16:9 est acceptée par Seedance 2.0, Veo 3.1 et Wan 2.7. Une requête de 5 secondes est en revanche valide sur Seedance 2.0 et Wan 2.7, mais pas sur Veo 3.1. Au moment de la publication du guide, Veo 3.1 accepte des durées de 4, 6 ou 8 secondes, Seedance 2.0 de 4 à 15 secondes et Wan 2.7 de 2 à 10 secondes ; ce dernier propose du 720p ou du 1080p. Ces valeurs sont à revérifier via /api/v1/videos/models, les capacités pouvant évoluer.

Ce même endpoint expose allowed_passthrough_parameters pour les fonctions propres à un modèle. Ces clés peuvent être envoyées dans l'objet provider.options, organisé par slug de provider ; seules les options destinées au provider qui sert effectivement la requête sont transmises, et les clés non reconnues sont ignorées. Ce mécanisme permet donc de conserver un cycle d'appel commun tout en faisant passer des réglages spécifiques au modèle ou au provider.

Pour le coût, /api/v1/videos/models expose aussi les pricing_skus des modèles. OpenRouter recommande de les consulter avant un lot pour estimer le coût, puis de comparer cette estimation au coût réellement retourné dans l'objet usage d'un job terminé. Cet objet peut contenir cost et l'indicateur is_byok. Le guide déconseille de coder une formule de coût universelle, la tarification dépendant du modèle et de la configuration.

Côté recommandations opérationnelles, OpenRouter préconise un intervalle de polling de 30 secondes et un timeout d'une heure (soit 3 600 secondes) pour éviter qu'un job ne laisse un processus tourner indéfiniment. Ces valeurs restent des recommandations, pas un contrat documenté.

Une fois le job terminé, le tableau unsigned_urls renvoie vers le contenu généré. Malgré son nom, ces URLs ne sont pas présignées : leur récupération nécessite toujours le bearer token dans l'en-tête Authorization. Le statut expired correspond à un job ayant dépassé sa durée de vie, et OpenRouter recommande de déplacer rapidement les vidéos terminées vers un stockage que nous maîtrisons plutôt que de considérer l'endpoint de génération comme un hébergement permanent.

Pourquoi l'asynchrone n'est pas un détail d'implémentation

Garder une requête HTTP ouverte pendant toute la durée d'une génération vidéo cause directement des problèmes de fragilité : fermeture de session, dépassement de limite d'exécution, timeout de proxy. L'architecture asynchrone avec job ID persistant résout ce problème en permettant de reprendre un job même après un redémarrage de l'application.

C'est un choix d'architecture qui a des conséquences sur le workflow développeur. Un timeout temporaire lors du polling ne prouve pas que la génération elle-même a échoué — un point que le guide souligne explicitement. Dans le pire des cas, un job peut d'ailleurs s'exécuter jusqu'à un intervalle de polling au-delà du timeout nominal.

Le polling convient aux scripts, prototypes et petits volumes. Lorsqu'un grand nombre de générations s'exécutent en parallèle, OpenRouter documente une alternative par webhook : un callback_url HTTPS peut être fourni lors de la soumission, soit pour une requête précise, soit comme valeur par défaut du workspace, la valeur de la requête étant prioritaire. Le webhook est envoyé lorsque le job atteint un état terminal. Chaque livraison comporte un en-tête X-OpenRouter-Idempotency-Key à conserver pour éviter de traiter deux fois le même événement. Si un secret de signature est configuré, l'en-tête X-OpenRouter-Signature doit être vérifié contre le corps brut de la requête avant son traitement.

Un autre point compte pour les projets clients : la génération vidéo n'est pas éligible au Zero Data Retention. OpenRouter explique que l'étape de récupération asynchrone impose une rétention brève de la sortie afin qu'elle puisse être téléchargée ; les requêtes avec ZDR imposé ne sont donc pas routées vers la génération vidéo.

Ce que l'API unifiée change réellement

Le guide documente un avantage précis : l'endpoint, l'authentification, la forme générale des réponses, le suivi des statuts et la logique de téléchargement restent les mêmes lorsque nous passons de Seedance à Veo ou Wan. Sans cette couche commune, une intégration directe auprès d'un autre fournisseur peut nécessiter de nouveaux endpoints, paramètres, statuts, variables d'environnement et traitements d'erreur.

Cette uniformité ne rend toutefois pas les modèles interchangeables dans tous les cas. Le champ model change en une ligne, mais les durées, résolutions, ratios, options audio et paramètres spécifiques doivent toujours être validés pour le modèle choisi. OpenRouter expose ces différences via /api/v1/videos/models plutôt que de les masquer derrière une interface supposée identique.

Pour une intégration en production, le guide recommande enfin de persister chaque job ID dès la soumission, de distinguer les erreurs de polling des échecs réels de génération et de limiter les nouvelles soumissions afin d'éviter les doublons et les coûts associés.