Skip to main content

VideoRetalk API reference

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.

Ce 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.

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

ChampTypeEmplacementObligatoireDescriptionExemple
Content-TypeStringHeaderOuiapplication/jsonapplication/json
AuthorizationStringHeaderOuiClé API (format : Bearer VOTRE_CLÉ)Bearer d1**2a
X-DashScope-AsyncStringHeaderOuiDéfinissez sur enable pour activer la création asynchrone de tâches.enable
modelStringBodyOuiModèle à appeler.videoretalk
input.video_urlStringBodyOuiURL 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_urlStringBodyOuiURL 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_urlStringBodyNonURL 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_extensionBooleanBodyNonIndique 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_thresholdIntegerBodyNonDé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

ChampTypeDescriptionExemple
output.task_idStringID de la tâche interrogée.a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_statusStringÉ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_urlStringURL 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_durationFloatDurée de la vidéo générée (en secondes)."video_duration": 10,23
usage.video_ratioStringType 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.sizeStringRésolution de la vidéo générée (identique à celle de l'entrée)."size": "1080*1920"
usage.fpsIntegerFréquence d'images de la vidéo générée (identique à celle de l'entrée)."fps": 25
request_idStringID 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

  1. 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).
  2. 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.
  3. 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.
  4. 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.