跳转到主要内容
千问 AI 平台 home page
文档
VideoRetalk

声动人像 VideoRetalk — 创建任务

提交声动人像 VideoRetalk 视频口型替换异步任务

POST
/api/v1/services/aigc/image2video/video-synthesis
cURL
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
    }
  }'
{
  "output": {
    "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
    "task_status": "PENDING"
  },
  "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}
请先获取 API Key 并配置为环境变量。

模型概览

模型简介
模型名模型简介
videoretalk声动人像 VideoRetalk，基于人物视频和人声音频，生成人物讲话口型与输入音频相匹配的新视频。适用于视频配音、数字人口型替换等场景。

使用说明

  • 上传的视频、音频、图像文件支持 HTTP 链接，不支持本地路径。也可使用平台提供的临时存储空间上传本地文件并创建链接。
  • 如果使用临时存储空间上传文件后获取到的 oss:// 前缀 URL，在 HTTP 请求头中必须添加 X-DashScope-OssResourceResolve: enable 参数。未添加该参数会导致报错 No connection adapters were found for 'oss://...'。详细说明请参见上传文件获取临时 URL。

输入限制

视频要求
限制项要求
格式mp4、avi、mov
文件大小不超过 300 MB
时长2 秒到 120 秒之间
帧率15 fps 到 60 fps
编码H.264 或 H.265
边长640 到 2048 像素
内容人物正面出镜的近景画面，避免大角度侧脸或人脸过小
音频要求
限制项要求
格式wav、mp3、aac
文件大小不超过 30 MB
时长2 秒到 120 秒之间
内容需包含清晰、响亮的人声语音，已去除环境噪音和背景音乐
人物参考图要求（可选，用于多人场景指定目标人物）
限制项要求
格式jpeg、jpg、png、bmp、webp
文件大小不超过 10 MB
宽高比不超过 2
最大边长不超过 4096 像素
内容需包含一张清晰的人物正脸，且为视频中出现的人物

使用流程

  1. 调用本接口，将视频 URL、音频 URL 及可选参数一并提交，获取 task_id。
  2. 调用查询视频口型替换任务结果接口，使用 task_id 轮询任务状态，直到获取生成的视频 URL。

错误码

大模型服务通用状态码请查阅错误信息。本模型特定错误码：
HTTP 状态码错误码含义说明
400InvalidParameter缺少必填参数或格式错误
400InvalidURL.ConnectionRefused下载被拒绝，请提供可用的 URL
400InvalidURL.Timeout下载超时（60 秒超时）
400InvalidFile.Size视频/音频/图像文件大小超限
400InvalidFile.Format文件格式不符合要求
400InvalidFile.Resolution视频边长需介于 640–2048 之间
400InvalidFile.FPS视频帧率需介于 15–60 fps
400InvalidFile.Duration视频/音频时长需介于 2–120 秒
400InvalidFile.ImageSize图片大小超出限制（长宽比不大于 2，最长边不大于 4096）
400InvalidFile.Openerror视频/音频/图像文件无法打开
400InvalidFile.Content输入图片中没有人或有多人
400InvalidFile.FaceNotMatch参考图与视频人脸匹配失败

鉴权

​
string
header
必填

千问 AI 平台 API Key。详见获取 API Key。

Header 参数

​
enum<string>
必填

固定值 enable，启用异步模式。

可选值：enable

请求体

application/json
​
enum<string>
必填

模型名称，固定为 videoretalk。

可选值：videoretalk
​
object
必填
​
object

响应

200-application/json
​
string

本次请求的唯一 ID。

​
object