VideoRetalk API reference - Alibaba Cloud Model Studio - Centre de documentation Alibaba Cloud

L'API VideoRetalk génère des vidéos avec synchronisation labiale en remplaçant la parole d'une personne par une piste audio fournie.

ImportantCe document s'applique uniquement à la région China (Beijing). Pour utiliser le modèle, servez-vous d'une clé API de la région China (Beijing).

HTTP

VideoRetalk prend exclusivement en charge les appels HTTP et fonctionne de manière asynchrone : soumettez une tâche, puis interrogez les résultats via deux requêtes distinctes. Cette approche réduit les temps d'attente et évite les délais d'expiration.

Soumettre une tâche : envoyez une requête pour créer une tâche de génération vidéo. L'API retourne un ID de tâche.
Interroger l'état de la tâche et récupérer les résultats : utilisez l'ID de tâche retourné pour vérifier son état et obtenir la vidéo générée.

Prérequis

Vous avez créé une clé API et défini cette clé comme variable d'environnement.

Limitations des entrées

Exigences relatives à la vidéo :
- Fichier : MP4, AVI ou MOV. Taille maximale : 300 Mo. Durée : 2 à 120 secondes.
- Propriétés : fréquence d'images de 15 à 60 ips. Encodage H.264 ou H.265 obligatoire. Dimensions : 640 à 2 048 pixels.
- Contenu : plan rapproché d'une personne face à la caméra. Évitez les angles extrêmes ou les visages trop petits. Si la vidéo ne contient aucun visage, reportez-vous à la section FAQ.
Exigences relatives à l'audio :
- Fichier : WAV, MP3 ou AAC. Taille maximale : 30 Mo. Durée : 2 à 120 secondes. Si les durées audio et vidéo diffèrent, consultez la section FAQ.
- Contenu : voix humaine claire et forte. Supprimez les bruits ambiants et la musique de fond.
Exigences relatives à l'image de référence du personnage :
- Fichier : JPEG, JPG, PNG, BMP ou WebP. Taille maximale : 10 Mo. Ratio d'aspect inférieur ou égal à 2 ; côté le plus long : 4 096 pixels maximum.
- Contenu : vue frontale nette du visage. La personne doit apparaître dans la vidéo. Vous pouvez utiliser une capture d'écran de la vidéo.
Exigences relatives aux URL de fichiers :
- Les fichiers doivent être accessibles via des liens HTTP (chemins locaux non pris en charge). Utilisez l'espace de stockage temporaire de la plateforme pour télécharger vos fichiers locaux et générer des liens.

Soumettre une tâche

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/

Paramètres de la requête

Champ	Type	Emplacement	Obligatoire	Description	Exemple
Content-Type	String	Header	Oui	application/json	application/json
Authorization	String	Header	Oui	Clé API (format : Bearer VOTRE_CLÉ)	Bearer d1**2a
X-DashScope-Async	String	Header	Oui	Définissez sur `enable` pour activer la création asynchrone de tâches.	enable
model	String	Body	Oui	Modèle à appeler.	videoretalk
input.video_url	String	Body	Oui	URL du fichier vidéo téléchargé. Consultez la section Limitations des entrées pour connaître les exigences applicables aux fichiers.	http://aaa/bbb.mp4
input.audio_url	String	Body	Oui	URL du fichier audio téléchargé. Consultez la section Limitations des entrées pour connaître les exigences applicables aux fichiers.	http://aaa/bbb.wav
input.ref_image_url	String	Body	Non	URL de l'image de référence du visage. Ce paramètre permet de spécifier le visage à synchroniser lorsque plusieurs visages sont présents. S'il est omis, le système sélectionne automatiquement le visage le plus grand de la première image. Reportez-vous à la section Limitations des entrées pour les exigences relatives aux fichiers.	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	Non	Indique si la vidéo doit être étendue lorsque l'audio est plus long. Valeur par défaut : `false`. `true` : prolonge la vidéo pour correspondre à la durée de l'audio en bouclant selon un motif « lecture inversée, lecture normale ». `false` : n'étend pas la vidéo. La vidéo générée conserve la durée originale et l'audio est tronqué.	false
parameters.query_face_threshold	Integer	Body	Non	Définit le niveau de confiance pour la correspondance des visages lorsqu'une image de référence est fournie. Plage : 120-200 (une valeur faible assouplit la correspondance, une valeur élevée la rend plus stricte). Valeur par défaut : 170. Ce paramètre est ignoré si input.ref_image_url est vide.	170

Paramètres de la réponse

Champ	Type	Description	Exemple
output.task_id	String	ID de la tâche soumise. Utilisez-le pour interroger l'état de la tâche et récupérer les résultats.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	État de la tâche après soumission.	"PENDING"
request_id	String	ID de la requête.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Exemple de requête

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "videoretalk",
    "input": {
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/aumwir/stella2-%E6%9C%89%E5%A3%B0%E4%B9%A67.wav",
        "ref_image_url": ""
     },
    "parameters": {
        "video_extension": false
    }
  }'

Exemple de réponse

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
        "task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Interroger l'état de la tâche et récupérer les résultats

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Paramètres de la requête

Champ	Type	Emplacement	Obligatoire	Description	Exemple
Authorization	String	Header	Oui	Clé API (format : Bearer VOTRE_CLÉ)	Bearer d1**2a
task_id	String	Url Path	Oui	ID de la tâche à interroger (retourné par l'API de soumission de tâche).	a8532587-fa8c-4ef8-82be-0c46b17950d1

Paramètres de la réponse

Champ	Type	Description	Exemple
output.task_id	String	ID de la tâche interrogée.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	État de la tâche interrogée.	États possibles de la tâche : PENDING PRE-PROCESSING RUNNING POST-PROCESSING SUCCEEDED FAILED UNKNOWN : la tâche n'existe pas ou son état est inconnu.
output.video_url	String	URL de la vidéo générée. Valide pendant 24 heures après l'achèvement de la tâche.	https://xxx/1.mp4"
usage.video_duration	Float	Durée de la vidéo générée (en secondes).	"video_duration": 10,23
usage.video_ratio	String	Type de ratio d'aspect de la vidéo générée. Valeur : standard (la sortie correspond à l'original par défaut).	"video_ratio": "standard"
usage.size	String	Résolution de la vidéo générée (identique à celle de l'entrée).	"size": "1080*1920"
usage.fps	Integer	Fréquence d'images de la vidéo générée (identique à celle de l'entrée).	"fps": 25
request_id	String	ID de la requête.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Exemple de requête

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Exemple de réponse

{
    "request_id": "87b9dce5-7f36-4305-a347-xxxxxx",
    "output": {
        "task_id": "3afd65eb-9604-48ea-8a91-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 20:15:29.887",
        "scheduled_time": "2025-09-11 20:15:36.741",
        "end_time": "2025-09-11 20:16:40.577",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 7.2,
        "size": "1080*1920",
        "video_ratio": "standard",
        "fps": 25
    }
}

Exemple de réponse d'erreur

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
        "task_status": "FAILED",
        "code": "xxx",
        "message": "xxxxxx"
    }
}

Codes d'erreur

Consultez la rubrique Codes d'erreur pour les codes d'état généraux.

Codes d'erreur spécifiques au modèle :

Code de retour HTTP	Code d'erreur	Message d'erreur	Description
400	InvalidParameter	Field required: xxx	Paramètre de requête manquant ou incorrect.
400	InvalidURL.ConnectionRefused	Connection to ${url} refused, please provide avaiable URL	Téléchargement refusé. Fournissez une URL valide.
400	InvalidURL.Timeout	Download ${url} timeout, please check network connection.	Délai d'attente dépassé lors du téléchargement (timeout : 60 s).
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	La taille du fichier doit être inférieure à ** Mo.
400	InvalidFile.Format	Invalid file format，the request file format is one of the following types: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP, and WEBP.	Format de fichier invalide. Formats pris en charge : Vidéo (MP4/AVI/MOV), Audio (MP3/WAV/AAC), Image (JPG/JPEG/PNG/BMP/WebP).
400	InvalidFile.Resolution	Invalid video resolution. The height or width of video must be 640 ~ 2048.	Les dimensions latérales de la vidéo doivent être comprises entre 640 et 2 048 pixels.
400	InvalidFile.FPS	Invalid video FPS. The video FPS must be 15 ~ 60.	La fréquence d'images de la vidéo doit être comprise entre 15 et 60 ips.
400	InvalidFile.Duration	Invalid file duration. The video/audio file duration must be 2s ~ 120s.	La durée de la vidéo ou de l'audio doit être comprise entre 2 et 120 secondes.
400	InvalidFile.ImageSize	The size of image is beyond limit.	La taille de l'image dépasse la limite autorisée. Le ratio d'aspect doit être inférieur ou égal à 2 et le côté le plus long ne doit pas excéder 4 096 pixels.
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	Impossible d'ouvrir le fichier.
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	L'image ne contient aucune personne ou en contient plusieurs.
400	InvalidFile.FaceNotMatch	There are no matched face in the video with the provided reference image.	Aucun visage de la vidéo ne correspond au visage de référence fourni.

FAQ

Comment gérer des durées différentes entre la vidéo et l'audio d'entrée ?
Par défaut, le fichier le plus long est tronqué pour s'aligner sur le plus court. Pour boucler la vidéo afin qu'elle corresponde à la durée de l'audio, définissez video_extension sur true (lecture inversée puis normale).
Comment l'API traite-t-elle les segments silencieux dans l'audio d'entrée ?
Le modèle génère des images avec la bouche fermée pour les segments audio silencieux.
Que se passe-t-il lorsqu'une image vidéo ne contient aucun visage alors que l'audio correspondant comporte de la parole ?
L'image originale est conservée et l'audio continue. La synchronisation labiale ne s'applique qu'aux images contenant des visages détectables.
Comment sélectionner une personne spécifique pour la synchronisation labiale dans une vidéo comportant plusieurs personnes ?
L'API ne synchronise qu'une seule personne. Utilisez input.ref_image_url pour spécifier le visage cible. En l'absence de ce paramètre, le visage le plus grand de la première image est synchronisé automatiquement.