Format vidéo OpenAI

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": "..."}} ; le point de terminaison de téléchargement du contenu utilise aussi cette forme objet. Voir Erreurs courantes.

POST /v1/videos et GET /v1/videos/{task_id} sont le dialecte vidéo OpenAI de la même API de tâches asynchrones décrite dans Créer une tâche vidéo et Obtenir une tâche vidéo. Le corps de soumission utilise les mêmes champs ; la différence est la réponse : la réponse de soumission comme le GET renvoient un objet vidéo OpenAI plutôt que l’enregistrement de tâche. C’est le format utilisé par les modèles Sora, et celui qu’attend le client vidéo du SDK OpenAI.

Points de terminaison

Méthode	Chemin	Rôle
POST	/v1/videos	Soumettre une tâche de génération
GET	/v1/videos/{task_id}	Lire la tâche comme objet vidéo OpenAI
GET	/v1/videos/{task_id}/content	Télécharger les octets de la vidéo terminée
POST	/v1/videos/{video_id}/remix	Créer une tâche dérivée d’une vidéo existante

Soumettre

curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A calico cat playing a piano on stage",
    "size": "1280x720",
    "seconds": "4"
  }'

Les champs de requête sont ceux de Créer une tâche vidéo : model, prompt, seconds / duration, size, input_reference, images et metadata. input_reference est honoré par les modèles qui prennent en charge une image de référence. multipart/form-data est aussi accepté, un fichier peut donc être envoyé directement :

curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "size=1280x720" \
  -F "seconds=4" \
  -F "input_reference=@cat.jpg"

Réponse de soumission

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

id est l’ID de tâche RouteAPI. task_id est un alias de compatibilité qui peut disparaître des futures réponses ; lisez id. Adressez toujours la tâche par cet id ; les identifiants présents dans la charge utile amont stockée ne sont pas la valeur à interroger ni à télécharger.

La réponse de soumission porte aussi un en-tête X-New-Api-Other-Ratios avec les multiplicateurs de facturation appliqués, par exemple {"seconds":5,"size":1} pour une requête Sora.

Obtenir l’objet vidéo

GET /v1/videos/{task_id}

curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1792048458,
  "completed_at": 1792048569,
  "metadata": { "url": "https://...mp4" }
}

Champ	Description
id	ID de tâche RouteAPI
object	Toujours "video"
model	Modèle qui a exécuté la tâche
status	queued, in_progress, completed ou failed
progress	Entier de 0 à 100
created_at / completed_at	Secondes Unix. Certains adaptateurs remplissent completed_at avec la dernière mise à jour de la ligne : déterminez la fin à partir de status, pas de ce champ
expires_at, size, seconds, remixed_from_video_id	Présents uniquement lorsque le fournisseur les renvoie
metadata.url	URL de la vidéo pour les fournisseurs qui la rapportent via l’objet vidéo. Utilisez /v1/videos/{task_id}/content si vous voulez les octets quel que soit le fournisseur
error.code / error.message	Définis lorsque la tâche a échoué, par exemple expired ou cancelled pour Seedance

Les champs propres à la charge utile amont (comme expires_at ou size) n’apparaissent que si le fournisseur les renvoie ; l’ensemble ci-dessus est ce que RouteAPI garantit de mapper. Sur les canaux Gemini et Vertex, le statut de la tâche est rafraîchi depuis le fournisseur avant la construction de cet objet.

Quels statuts sont terminaux

completed et failed sont les deux seuls statuts terminaux. Une tâche qui renvoie failed a déjà été remboursée ; la réessayer est inutile, soumettez une nouvelle tâche.

La tâche est limitée à l’utilisateur de la clé API : un id appartenant à un autre compte est signalé comme task_not_exist, exactement comme sur le point de terminaison d’enregistrement de tâche.

Télécharger le contenu

GET /v1/videos/{task_id}/content

Renvoie les octets de la vidéo, diffusés via RouteAPI. La réponse porte Cache-Control: public, max-age=86400 et le Content-Type amont. La route accepte une clé API ou une session console et ne sert que les tâches appartenant à l’appelant. Voir Télécharger la vidéo pour les codes d’erreur et un exemple curl.

Remix

POST /v1/videos/{video_id}/remix

Crée une nouvelle tâche à partir d’une vidéo existante. RouteAPI cherche video_id parmi vos tâches, en déduit le modèle et épingle la requête sur le canal qui a produit la vidéo d’origine pour que le résultat reste compatible.

curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/remix \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "The same cat, now wearing a tiny hat" }'

Le remix a du sens pour la famille Sora (sora-2, sora-2-pro), où la requête est transmise au point de terminaison de remix de l’amont et où prompt est obligatoire. Pour les autres plateformes, la requête est quand même acceptée, le modèle et le canal sont résolus depuis la tâche d’origine, et la tâche est construite par l’adaptateur de ce modèle — mais l’amont ne reçoit jamais d’instruction de remix, donc la nouvelle tâche est une génération ordinaire, pas une dérivée de video_id.

Le remix hérite des multiplicateurs de facturation de la tâche d’origine lorsque l’adaptateur les a enregistrés, la nouvelle tâche est donc facturée comme l’original plutôt qu’à partir de valeurs par défaut.

Sora

Les modèles Sora utilisent directement cette famille de points de terminaison ; les paramètres qui comptent sont size et seconds.

Modèle	Tailles acceptées
sora-2	720x1280, 1280x720
sora-2-pro	720x1280, 1280x720, 1792x1024, 1024x1792

• Une taille non prise en charge renvoie 400 avec le code invalid_size avant toute réservation.
• Les valeurs par défaut sont 720x1280 et 4 secondes.
• seconds (ou duration) est validé comme pour tout autre modèle vidéo : les valeurs négatives et celles supérieures à 3600 sont rejetées avec 400 invalid_seconds.
• input_reference est transmis comme image de référence ; les soumissions JSON et multipart fonctionnent.
• La facturation est calculée à partir de seconds et size : une sortie 1792x1024 ou 1024x1792 coûte un multiplicateur de taille (1.666667) en plus du tarif par seconde. Les multiplicateurs appliqués sont renvoyés dans X-New-Api-Other-Ratios.
• Le remix est pris en charge sur cette famille.

La disponibilité et le prix dépendent du compte — vérifiez que le modèle apparaît dans GET /v1/models et consultez la page de détail du modèle.

Erreurs

La forme d’erreur de tâche s’applique une fois routé :

Statut	Code	Signification
400	invalid_request	prompt absent ou vide, corps mal formé, ou champ de mauvais type
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	task_not_exist	Le video_id d’un remix est inconnu ou appartient à un autre compte
400	task_source_unavailable	Le canal de la tâche d’origine a été supprimé ou désactivé, ou son adaptateur est absent
400	asset_remix_conflict	Un remix d’une tâche non-asset a tenté de référencer un matériel asset://
429	—	Capacité amont épuisée ; le message est remplacé par un avis générique de réessai
500	build_request_failed, do_request_failed	La tâche n’a pas pu être convertie ou la connexion amont a échoué
500	convert_to_openai_video_failed	Les données de tâche stockées n’ont pas pu être converties en objet vidéo
501	not_implemented	GET /v1/videos/{task_id} sur une plateforme dont l’adaptateur n’a pas de conversion vidéo OpenAI
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 utilisent à la place le corps standard {"error": {"message": ..., "type": "error", "code": ...}}.

Pour aller plus loin

• Créer une tâche vidéo — l’enveloppe de requête commune et les erreurs de soumission.
• Obtenir une tâche vidéo — le dialecte d’enregistrement de tâche, les statuts et le téléchargement du contenu.
• Seedance, Hailuo, Wan — paramètres propres à chaque modèle.