Créer une tâche vidéo

Informations communes

• URL de base : https://api.routeapi.ai
• Authentification : Authorization: Bearer $ROUTEAPI_KEY avec une clé API commençant par sk- (à créer sur la page Clés API). Les clés de gestion commençant par rat_ ne peuvent pas appeler de modèle.
• Format d’erreur : une fois la requête routée, les points de terminaison de tâches répondent avec {"code": "...", "message": "...", "data": null}. Les requêtes rejetées avant le routage (clé API absente ou invalide, restriction IP, groupe ou modèle non autorisé) utilisent le corps standard {"error": {"message": "...", "type": "error", "code": "..."}}. Voir Erreurs courantes pour la signification des codes de statut.

La génération vidéo sur RouteAPI est une API de tâches asynchrones. Vous soumettez une requête, recevez un task_id, interrogez cette tâche jusqu’à son état terminal, puis téléchargez la vidéo. Tous les modèles vidéo de la plateforme — Seedance, Sora, Veo, Wan, Kling, Hailuo, Vidu et d’autres — sont appelés via les mêmes points de terminaison, car RouteAPI convertit votre requête dans la forme attendue par l’amont sélectionné.

Les modèles vidéo apparaissent dans GET /v1/models ; leur supported_endpoint_types affiche openai-video pour les canaux servis via le format vidéo OpenAI, et la page du modèle dans la console permet de le définir par modèle. Dans tous les cas, prenez l’ID de modèle dans cette liste — voir Modèles. Les paramètres propres à chaque modèle sont documentés par fournisseur : Seedance, Hailuo, Wan. Le dialecte OpenAI/Sora de la même API est décrit dans Format vidéo OpenAI.

Points de terminaison

Méthode	Chemin	Rôle	Documenté dans
POST	/v1/video/generations	Soumettre une tâche de génération	Cette page
GET	/v1/video/generations/{task_id}	Lire l’enregistrement de tâche	Obtenir une tâche vidéo
POST	/v1/videos	Soumettre une tâche de génération (dialecte OpenAI)	Format vidéo OpenAI
GET	/v1/videos/{task_id}	Lire la tâche comme objet vidéo OpenAI	Format vidéo OpenAI
POST	/v1/videos/{video_id}/remix	Créer une tâche dérivée d’une vidéo existante	Format vidéo OpenAI
GET	/v1/videos/{task_id}/content	Télécharger les octets de la vidéo terminée	Obtenir une tâche vidéo

POST /v1/video/generations et POST /v1/videos sont deux chemins vers la même opération de tâche, avec des dialectes de requête et de réponse différents. La réponse de soumission est un objet vidéo OpenAI dans les deux cas ; les GET diffèrent (enregistrement de tâche vs objet vidéo), donc associez chaque chemin de soumission à son GET correspondant.

Déroulement d’une tâche

1. Soumettre — envoyez le prompt et le modèle à POST /v1/video/generations (ou POST /v1/videos) et conservez le task_id renvoyé. Le coût estimé est réservé sur votre solde à cette étape.
2. Interroger — appelez le GET correspondant toutes les 10 à 15 secondes. La génération prend généralement d’une à plusieurs minutes ; une résolution plus élevée et une durée plus longue prennent plus de temps.
3. Terminer — lorsque le statut indique un succès, téléchargez la vidéo ou lisez son URL. Si la tâche échoue ou n’atteint jamais un état terminal, le montant réservé est restitué.

Note

RouteAPI interroge le fournisseur amont en arrière-plan environ toutes les 15 secondes, donc votre propre interrogation ne fait que lire l’enregistrement de tâche. Une tâche qui n’atteint jamais un état terminal est marquée en échec et remboursée après le délai d’expiration de la plateforme (24 heures par défaut), vous n’avez donc pas besoin de réessayer indéfiniment.

Soumettre une tâche

POST /v1/video/generations

Champs de requête

Chaque modèle vidéo accepte cette enveloppe commune. Les options propres au modèle vont dans metadata ; les pages fournisseur listent les clés réellement lues par chaque adaptateur.

Champ	Type	Obligatoire	Description
model	string	Oui	ID de modèle issu de GET /v1/models
prompt	string	Oui	Prompt texte. Un prompt absent, vide ou composé d’espaces est rejeté avec 400
image	string	Non	Image unique (URL ou Base64/data URI). Traitée comme la première entrée de images
images	string[]	Non	Images de référence / première image. Le sens dépend du modèle
size	string	Non	Indication de taille ou de résolution comme 1280x720 ou 720p, selon le modèle
duration	integer	Non	Durée en secondes. RouteAPI rejette les valeurs négatives et celles supérieures à 3600
seconds	string	Non	Forme chaîne héritée de la durée. Les modèles qui la lisent l’utilisent à la place de duration
input_reference	string	Non	Champ d’image de référence au format OpenAI, lu par les adaptateurs qui le prennent en charge (Sora et Wan par exemple)
ratio	string	Non	Ratio d’image comme 16:9 ou 9:16 ; lu par l’adaptateur Seedance
resolution	string	Non	Palier de résolution de sortie comme 720p ou 1080p ; lu par l’adaptateur Seedance
generate_audio	boolean	Non	Générer une piste audio. Sur Seedance, un false explicite est transmis et non supprimé
metadata	object	Non	Paramètres propres au fournisseur. Pour Seedance, la valeur de metadata l’emporte sur celle du niveau supérieur en cas de doublon

Les champs de niveau supérieur que RouteAPI ne reconnaît pas sont ignorés ; placez les paramètres propres au modèle sous metadata.

Les corps multipart/form-data sont aussi acceptés sur les points de terminaison de soumission : les champs de formulaire scalaires correspondent aux mêmes noms, et les fichiers sont envoyés directement (par exemple input_reference pour Sora). Les champs de formulaire inconnus deviennent des entrées metadata.

Attention

Tous les fournisseurs ne lisent pas tous les champs communs. ratio, resolution et generate_audio sont interprétés par l’adaptateur Seedance ; Veo lit metadata.durationSeconds, metadata.resolution et metadata.aspectRatio avec size en repli ; Wan lit size et metadata ; Sora lit size, seconds et les images d’entrée. Consultez la page du fournisseur avant de compter sur un champ, car un champ non reconnu est silencieusement ignoré plutôt que rejeté.

Exemple de soumission

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "An orange cat stretching on a windowsill at sunrise",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

Réponse de soumission

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

task_id (et son alias id) est l’ID de tâche RouteAPI ; tous les appels suivants l’utilisent. L’ID de tâche du fournisseur amont n’est pas la valeur à interroger — quand il est visible, il se trouve dans la charge utile amont stockée (data.data sur l’enregistrement de tâche).

Une soumission réussie renvoie aussi un en-tête X-New-Api-Other-Ratios contenant les multiplicateurs de facturation appliqués — par exemple {"seconds":5,"size":1} pour Sora, ou {"video_input":0.608695652174} pour une requête Seedance avec entrée vidéo. Il est utile pour rapprocher la facturation.

Erreurs de soumission

Une fois routés, les points de terminaison de tâches répondent avec la forme d’erreur des tâches :

{ "code": "invalid_request", "message": "prompt is required", "data": null }

Statut	Code	Signification
400	invalid_request	prompt absent ou vide, champ metadata de mauvais type, ou corps illisible
400	invalid_json	JSON invalide sur les adaptateurs qui valident eux-mêmes le corps (Sora et Wan)
400	missing_model	model est absent ; renvoyé par les adaptateurs qui valident eux-mêmes le corps (Sora et Wan). Les autres chemins rejettent une requête sans modèle avant le routage, sous forme d’erreur de middleware
400	invalid_seconds	duration / seconds est négatif ou supérieur à 3600
400	invalid_size	Le modèle n’accepte pas cette taille, par exemple une taille Sora non prise en charge
400	model_price_error	RouteAPI n’a pas pu tarifer le modèle ; rien n’est soumis
400	model_not_supported	Le modèle correspond à un modèle que le canal ne sert plus, comme Seedance 1.x
400	task_not_exist	Tâche d’origine d’un remix inconnue ou appartenant à un autre compte
400	task_source_unavailable	Le canal de la tâche d’origine d’un remix a été supprimé ou désactivé, ou son adaptateur est absent
403	insufficient_user_quota / pre_consume_token_quota_failed	Le solde du compte ou le quota de la clé ne couvre pas le coût estimé ; rien n’est soumis
429	—	Capacité amont épuisée ; le message est remplacé par un texte générique « réessayez plus tard »
500	build_request_failed, do_request_failed, invalid_response	La tâche n’a pas pu être convertie, la connexion amont a échoué, ou l’amont n’a renvoyé aucun ID de tâche
500	get_channel_failed, task_persistence_failed, gen_relay_info_failed	RouteAPI n’a pas pu router ou enregistrer la tâche ; rien n’est facturé (toute réservation est restituée)
502	upstream_task_id_missing	L’amont a accepté la tâche mais n’a renvoyé aucun ID de tâche ; la tâche est marquée en échec pour libérer la réservation
quelconque	fail_to_fetch_task	L’amont a répondu à la soumission avec un statut non 200 ; le statut HTTP est celui de l’amont

Les requêtes rejetées avant le routage — clé API absente ou invalide (401), restriction IP, groupe sans accès, modèle hors de la liste autorisée de la clé (403), ou modèle sans canal disponible (503, code model_not_found) — utilisent le corps d’erreur standard du middleware {"error": {"message": ..., "type": "error", "code": ...}}, et non la forme de tâche.

Les échecs survenant après la soumission (modération de contenu, expiration du fournisseur, annulation) n’apparaissent pas comme des erreurs HTTP. Ils apparaissent comme FAILURE dans l’enregistrement de tâche avec un fail_reason, et le montant réservé est restitué.

Pour aller plus loin

• Obtenir une tâche vidéo — interroger l’enregistrement, lire le statut et télécharger le résultat.
• Seedance, Hailuo, Wan — paramètres et limites propres à chaque modèle.
• Assets — téléverser des images, vidéos et audios réutilisables et les référencer avec asset://.
• Erreurs courantes — codes de statut communs à tous les points de terminaison de modèles.