VideoRetalk视频生成 API详情_大模型服务平台百炼(Model Studio)-阿里云帮助中心

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

模型概览

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

HTTP调用接口

功能描述

用于生成人物口型替换视频。

前提条件

已开通百炼服务并获得API-KEY：获取API Key。

输入限制

视频要求：
- 文件限制：支持mp4、avi、mov，文件≤300MB，2s＜时长＜2min。
- 视频限制：15fps≤帧率≤60fps；编码采用H.264或H.265；边长不低于640，不大于2048。
- 视频内容：视频应为人物正面出镜的近景画面。避免大角度侧脸或人脸过小。
音频要求：
- 文件限制：支持wav、mp3、aac，文件≤30MB，2s＜时长＜2min。
- 音频内容：音频中需包含清晰、响亮的人声语音，并去除了环境噪音、背景音乐等声音干扰信息。
人物参考图要求：
- 文件限制：支持jpeg、jpg、png、bmp、webp，文件≤10MB。
- 图片内容：需包含一张清晰的人物正脸，且该人物出现在视频画面中。也可从视频画面中截图用作人物参考图。
上传文件链接要求：
- 上传的视频、音频、图像文件支持HTTP链接，不支持本地路径。也可使用平台提供的文件存储API，上传本地文件并创建链接。

作业提交接口

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

说明

因该算法调用耗时较长，故采用异步调用的方式提交任务。
任务提交之后，系统会返回对应的作业ID，后续可通过“作业任务状态查询和结果获取接口”获取任务状态及对应结果。

入参描述

字段	类型	传参方式	必选	描述	示例值
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； 15fps≤帧率≤60fps；推荐采用H.264或H.265编码；边长不低于640，不大于2048；时长不小于2s且不大于120s；格式支持：mp4、avi、mov。视频内容：人物正面出镜的近景画面。避免大角度侧脸或人脸过小。	http://aaa/bbb.mp4
input.audio_url	String	Body	是	用户上传的音频文件 URL。音频文件要求：文件≤30MB ；时长不小于2s且不大于120s；格式支持：wav、mp3、aac。	http://aaa/bbb.wav
input.ref_image_url	String	Body	否	用户上传的人脸参考图 URL。用于指示需替换的对象，需包含一张清晰的人物正脸。若不输入人脸参考图，默认将选择视频中第一个有人脸的画面中，人脸占比最大的人物为目标。图像文件要求：文件≤10MB ；长宽比小于等于2，最大边长小于等4096；格式支持：jpeg、jpg、png、bmp、webp。	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	否	当输入的音频时长大于视频时长时，是否扩展视频长度，可设值为true或false。值为true时，使用原视频画面“倒放-正放”交替模式扩展视频时长，直至与音频相同。值为false时，不扩展画面长度，生成视频时长将与原视频相同。默认值为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 排队中 RUNNING 处理中 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.	参考图与视频人脸匹配失败

常见问题

输入语音和视频长度不一致，会如何处理？
默认将按音频、视频两者中时长较短的来截断。
当输入的音频时长大于视频时长时，并希望按音频长度来生成时，可将入参的视频扩展（parameters.video_extension）值设为true，算法将使用原视频画面“倒放-正放”交替模式扩展视频时长，直至与音频相同。
输入音频中有静音的情况，会如何处理？
音频静音的时段，预期视频中人物也会闭嘴。
输入视频的画面中有无人/脸拍不全的情况，会如何处理？
若音频中有人声，但画面无人或未出现人物嘴型，则保留原视频画面，音频正常播放。
输入视频的画面中有多人的情况，会如何处理？
仅支持替换一个人物。算法会按照输入人脸参考图（input.ref_image_url），识别指定人脸。若未输入人脸参考图，则默认选择第一个有人脸画面中，占比最大的人脸。