VideoRetalk 视频生成 API详情

声动人像VideoRetalk是一个人物视频生成模型,可基于人物视频和人声音频,生成人物讲话口型与输入音频相匹配的新视频。本文档介绍了该模型提供的视频生成能力的API调用方法。

模型概览

模型名

模型简介

videoretalk

videoretalk是一个人物视频生成模型,可基于人物视频和人声音频,生成人物讲话口型与输入音频相匹配的新视频。

HTTP调用接口

VideoRetalk视频生成API仅支持通过HTTP进行调用。为了减少等待时间并且避免请求超时,采用了异步处理方法。因此,您需要发起两个请求来生成视频。

前提条件

您需要已获取API Key配置API Key到环境变量

输入限制

  • 视频要求:

    • 文件限制:支持mp4、avi、mov,文件≤300MB,2秒<时长<120秒。

    • 视频限制:15fps≤帧率≤60fps;编码采用H.264H.265;边长不低于640,不大于2048。

    • 视频内容:视频应为人物正面出镜的近景画面。避免大角度侧脸或人脸过小。

  • 音频要求:

    • 文件限制:支持wav、mp3、aac,文件≤30MB,2秒<时长<120秒。

    • 音频内容:音频中需包含清晰、响亮的人声语音,并去除了环境噪音、背景音乐等声音干扰信息。

  • 人物参考图要求:

    • 文件限制:支持jpeg、jpg、png、bmp、webp,文件≤10MB。

    • 图片内容:需包含一张清晰的人物正脸,且该人物出现在视频画面中。也可从视频画面中截图用作人物参考图。

  • 上传文件链接要求:

    • 上传的视频、音频、图像文件支持HTTP链接,不支持本地路径。也可使用平台提供的文件存储API,上传本地文件并创建链接。

作业提交接口

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

入参描述

字段

类型

传参方式

必选

描述

示例值

Content-Type

String

Header

请求类型:application/json

application/json

Authorization

String

Header

API-Key,例如:Bearer d1**2a

Bearer d1**2a

X-DashScope-Async

String

Header

设置为enable,表明使用异步方式创建任务

enable

model

String

Body

指明需要调用的模型

videoretalk

input.video_url

String

Body

用户上传的视频文件 URL。

视频文件要求:

  • 大小:文件≤300MB

  • 格式:mp4、avi、mov

  • 时长:2秒<时长<120

  • 帧率:15fps≤帧率≤60fps

  • 编码:推荐采用H.264H.265编码

  • 边长:640≤边长≤2048

  • 内容:人物正面出镜的近景画面,避免大角度侧脸或人脸过小。如果视频的画面中人脸拍不全、没有人,请参考常见问题进行处理。

http://aaa/bbb.mp4

input.audio_url

String

Body

用户上传的音频文件 URL。

音频文件要求:

  • 大小:文件≤30MB

  • 格式:wav、mp3、aac

  • 时长:2秒<时长<120秒,如果视频和音频的时长不一致,请参考常见问题进行处理

  • 内容:音频中需包含清晰、响亮的人声语音,并去除了环境噪音、背景音乐等声音干扰信息。

http://aaa/bbb.wav

input.ref_image_url

String

Body

用户上传的人脸参考图 URL。

输入视频中包含多张人脸时,VideoRetalk视频生成API仅能选择一张人脸作为目标替换其口型,实现口型与音频相匹配的效果。此参数用来指定以哪个人物作为目标。

若不输入人脸参考图,默认将选择视频中第一个有人脸的画面中,人脸占比最大的人物为目标。

图像文件要求:

  • 文件大小:文件≤10MB

  • 图像大小:长宽比小于等于2,最大边长小于等4096

  • 格式:jpeg、jpg、png、bmp、webp

  • 内容:需包含一张清晰的人物正脸,且为视频中出现的人物

http://aaa/bbb.jpg

parameters.video_extension

Boolean

Body

当输入的音频时长大于视频时长时,是否扩展视频长度。默认值为false,可设置为truefalse

  • 值为true时,使用原视频画面“倒放-正放”交替模式扩展视频时长,直至与音频相同。

  • 值为false时,不扩展画面长度,生成视频时长将与原视频相同,音频将被截断。

false

出参描述

字段

类型

描述

示例值

output.task_id

String

提交异步任务的作业 ID,实际作业结果需要通过异步任务查询接口获取。

a8532587-fa8c-4ef8-82be-0c46b17950d1

output.task_status

String

提交异步任务后的作业状态。

“PENDING”

request_id

String

本次请求的系统唯一码。

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "videoretalk",
    "input": {
        "video_url": "http://xxx/1.mp4",
        "audio_url": "http://xxx/1.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"
}

作业任务状态查询和结果获取接口

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

入参描述

字段

类型

传参方式

必选

描述

示例值

Authorization

String

Header

API-Key,例如:Bearer d1**2a。

Bearer d1**2a

task_id

String

Url Path

需要查询作业的task_id,为作业提交接口返回的值。

a8532587-fa8c-4ef8-82be-0c46b17950d1

出参描述

字段

类型

描述

示例值

output.task_id

String

查询作业的 task_id。

a8532587-fa8c-4ef8-82be-0c46b17950d1

output.task_status

String

被查询作业的作业状态。

任务状态:

  • PENDING:排队中

  • PRE-PROCESSING:前置处理中

  • RUNNING:处理中

  • POST-PROCESSING:后置处理中

  • SUCCEEDED:成功

  • FAILED:失败

  • UNKNOWN:作业不存在或状态未知

output.video_url

String

生成的视频,video_url有效期为作业完成后24小时。

https://xxx/1.mp4"

usage.video_duration

Float

本次请求生成视频时长计量,单位:秒。

"video_duration": 10.23

usage.video_ratio

String

本次请求生成视频的画幅类型,该值为standard,默认按原视频比例输出。

"video_ratio": "standard"

request_id

String

本次请求的系统唯一码。

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

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

响应示例

{
    "request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output":{
        "task_id":"a8532587-fa8c-4ef8-82be-0c46b17950d1",
	"task_status":"SUCCEEDED",
        "video_url":"https://xxx/1.mp4"
    },
    "usage":{
        "video_duration": 10.23,
        "video_ratio": "standard"  
    }
}

异常响应示例

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

状态码说明

大模型服务通用状态码请查阅:错误码

同时本模型还有如下特定错误码:

HTTP 返回码

错误码(code)

错误信息(message)

含义说明

400

InvalidParameter

Field required: xxx

缺少入参,或格式错误

400

InvalidURL.ConnectionRefused

Connection to ${url} refused, please provide avaiable URL

下载被拒绝,请提供可用的url

400

InvalidURL.Timeout

Download ${url} timeout, please check network connection.

下载超时,60s超时

400

InvalidFile.Size

Invalid file size. The video/audio/image file size must be less than **MB.

视频/音频/图像文件必须小于**MB

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.

文件格式不符合要求,视频支持mp4、avi、mov;音频支持mp3, wav, aac;图片支持jpg, jpeg, png, bmp, webp

400

InvalidFile.Resolution

Invalid video resolution. The height or width of video must be 640 ~ 2048.

视频边长需介于640-2048之间

400

InvalidFile.FPS

Invalid video FPS. The video FPS must be 15 ~ 60.

视频帧率需介于15-60fps之间。

400

InvalidFile.Duration

Invalid file duration. The video/audio file duration must be 2s ~ 120s.

视频/音频时长需介于2-120s之间

400

InvalidFile.ImageSize

The size of image is beyond limit.

图片大小超出限制。

要求图片长宽比例不大于2,且最长边不大于4096

400

InvalidFile.Openerror

Invalid file, cannot open file as video/audio/image.

视频/音频/图像文件无法打开

400

InvalidFile.Content

The input image has no human body or multi human bodies. Please upload other image with single person.

输入图片中没有人或有多人

400

InvalidFile.FaceNotMach

There are no matched face in the video with the provided reference image.

参考图与视频人脸匹配失败

常见问题

  1. 输入语音和视频长度不一致,会如何处理?

    默认将按音频、视频两者中时长较短的来截断。

    当输入的音频时长大于视频时长时,并希望按音频长度来生成时,可将入参的视频扩展(parameters.video_extension)值设为true,算法将使用原视频画面“倒放-正放”交替模式扩展视频时长,直至与音频相同。

  2. 输入音频中有静音的情况,会如何处理?

    音频静音的时段,预期视频中人物也会闭嘴。

  3. 输入视频的画面中有无人/脸拍不全的情况,会如何处理?

    若音频中有人声,但画面无人或未出现人物嘴型,则保留原视频画面,音频正常播放。

  4. 输入视频的画面中有多人的情况,会如何处理?

    仅支持替换一个人物。算法会按照输入人脸参考图(input.ref_image_url),识别指定人脸。若未输入人脸参考图,则默认选择第一个有人脸画面中,占比最大的人脸。