通义万相-通用视频编辑API参考

本文介绍通义万相-视频编辑统一模型的输入输出参数。该模型支持文本、图像、视频等多种模态输入,可执行多种视频生成与编辑任务。

模型概览

模型名称

计费单价

限流(主账号与RAM子账号共用)

免费额度

任务下发接口RPS限制

同时处理中任务数量

wanx2.1-vace-plus

0.70元/秒

2

2

免费额度:50

有效期:阿里云百炼开通后180天内

更多说明请参见模型计费与限流

模型效果

模型功能

输入参考图

输入提示词

输出视频

多图参考

参考图1(参考主体)

image

参考图2(参考背景)

image

视频中,一位女孩自晨雾缭绕的古老森林深处款款走出,她步伐轻盈,镜头捕捉她每一个灵动瞬间。当女孩站定,环顾四周葱郁林木时,她脸上绽放出惊喜与喜悦交织的笑容。这一幕,定格在了光影交错的瞬间,记录下女孩与大自然的美妙邂逅。

输出视频

视频重绘

视频展示了一辆黑色的蒸汽朋克风格汽车,绅士驾驶着,车辆装饰着齿轮和铜管。背景是蒸汽驱动的糖果工厂和复古元素,画面复古与趣味

局部编辑

输入视频

输入掩码图像(白色区域表示编辑区域)

mask

视频展示了一家巴黎风情的法式咖啡馆,一只穿着西装的狮子优雅地品着咖啡。它一手端着咖啡杯,轻轻啜饮,神情惬意。咖啡馆装饰雅致,柔和的色调与温暖灯光映照着狮子所在的区域。

根据提示词修改编辑区域的内容

视频延展

输入首片段视频(1秒)

一只戴着墨镜的狗在街道上滑滑板,3D卡通。

输出延长后的视频(5秒)

视频画面扩展

一位优雅的女士正在激情演奏小提琴,她身后是一支完整的交响乐团

前提条件

通义万相-视频编辑统一模型的API目前仅支持通过HTTP进行调用。

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

HTTP调用

视频生成模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:

  1. 创建任务获取任务ID:首先发起创建任务请求,该请求会返回任务ID(task_id)。

  2. 根据任务ID查询结果:使用上一步获得的任务ID,查询任务状态及结果。任务成功执行时将返回视频URL,有效期24小时。

说明

创建任务后,该任务将被加入到排队队列,等待调度执行。后续需要调用“根据任务ID查询结果接口”获取任务状态及结果。

视频编辑统一模型的处理耗时较长(约5-10分钟),具体耗时受限于排队任务数量和服务执行情况,请您在获取结果时耐心等待。

步骤1:创建任务获取任务ID

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

请求参数

多图参考

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx2.1-vace-plus",
    "input": {
        "function": "image_reference",
        "prompt": "视频中,一位女孩自晨雾缭绕的古老森林深处款款走出,她步伐轻盈,镜头捕捉她每一个灵动瞬间。当女孩站定,环顾四周葱郁林木时,她脸上绽放出惊喜与喜悦交织的笑容。这一幕,定格在了光影交错的瞬间,记录下女孩与大自然的美妙邂逅。",
        "ref_images_url": [
            "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
            "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
        ]
    },
    "parameters": {
        "obj_or_bg": ["obj","bg"],
        "size": "1280*720"
    }
}'

视频重绘

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx2.1-vace-plus",
    "input": {
        "function": "video_repainting",
        "prompt": "视频展示了一辆黑色的蒸汽朋克风格汽车,绅士驾驶着,车辆装饰着齿轮和铜管。背景是蒸汽驱动的糖果工厂和复古元素,画面复古与趣味。",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_repainting_1.mp4"
    },
    "parameters": {
        "control_condition": "depth"
    }
}'

局部编辑

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx2.1-vace-plus",
    "input": {
        "function": "video_edit",
        "prompt": "视频展示了一家巴黎风情的法式咖啡馆,一只穿着西装的狮子优雅地品着咖啡。它一手端着咖啡杯,轻轻啜饮,神情惬意。咖啡馆装饰雅致,柔和的色调与温暖灯光映照着狮子所在的区域。",
        "mask_image_url": "http://wanx.alicdn.com/material/20250318/video_edit_1_mask.png",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_edit_2.mp4",
        "mask_frame_id": 1
    },
    "parameters": {
        "mask_type": "tracking",
        "expand_ratio": 0.05
    }
}'

视频延展

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx2.1-vace-plus",
    "input": {
        "function": "video_extension",
        "prompt": "一只戴着墨镜的狗在街道上滑滑板,3D卡通。",
        "first_clip_url": "http://wanx.alicdn.com/material/20250318/video_extension_1.mp4"
    },
    "parameters": {}
}'

视频画面扩展

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx2.1-vace-plus",
    "input": {
        "function": "video_outpainting",
        "prompt": "一位优雅的女士正在激情演奏小提琴,她身后是一支完整的交响乐团。",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_outpainting_1.mp4"
    },
    "parameters": {
        "top_scale": 1.5,
        "bottom_scale": 1.5,
        "left_scale": 1.5,
        "right_scale": 1.5
    }
}'
请求头(Headers)

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

X-DashScope-Async string (必选)

异步处理配置参数。HTTP请求只支持异步,必须设置为enable

请求体(Request Body)

多图参考

model string (必选)

模型名称。示例值:wanx2.1-vace-plus

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

提示词,用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

提示词技巧请参见文生视频/图生视频Prompt指南

function string (必选)

功能名称。多图参考设置为image_reference

多图参考支持最多3张参考图。图像内容可以包括主体与背景,例如人物、动物、服饰、场景等。使用 prompt 描述期望生成的视频画面内容,模型可将多张图片融合生成连贯的视频内容。

ref_images_url array[string] (必选)

输入参考图像的URL 数组。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

参考图像支持 1-3 张图像,若超过 3 张,则仅保留前 3 张作为输入。

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽和高范围在[360, 2000],单位像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

使用建议:

  • 若使用参考图像中的主体时,建议每张图像中仅包含一个主体。背景建议为纯色(如白色或单一颜色),以便更好地突出主体。

  • 若使用参考图像的背景时,背景图像最多只有一张,且背景图像中不包含任何主体对象。

parameters object (可选)

视频处理参数,如设置水印等。

属性

obj_or_bg array[string] (可选)

该参数用于标识每张参考图像的用途,与 ref_images_url 参数一一对应。数组中每个元素表示对应位置的图像为“主体”还是“背景”:

  • obj:表示该图像作为主体参考。

  • bg:表示该图像作为背景参考 (最多仅允许一个)。

使用说明:

  • 该参数的长度建议与 ref_images_url 一致;

  • 若未传入该参数,或长度不匹配,默认为 obj(主体)。

示例值: ["obj", "obj", "bg"]。

size string (可选)

生成视频的分辨率(宽*高)。目前支持生成720P 视频,分辨率的取值为:

  • 1280*720(默认值):视频宽高比为16:9。其中,1280代表宽度,720代表高度。

  • 720*1280:视频宽高比为9:16。

  • 960*960:视频宽高比为1:1。

  • 832*1088:视频宽高比为3:4。

  • 1088*832:视频宽高比为4:3。

duration integer (可选)

视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。

prompt_extend bool (可选)

是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。

  • true(默认值):开启智能改写。

  • false:关闭智能改写。

seed integer (可选)

随机数种子,用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

watermark bool (可选)

是否添加水印标识,水印位于图片右下角,文案为“AI生成”。

  • false(默认值):不添加水印。

  • true:添加水印。

视频重绘

model string (必选)

模型名称。示例值:wanx2.1-vace-plus

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

提示词,用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

提示词技巧请参见文生视频/图生视频Prompt指南

function string (必选)

功能名称。视频重绘设置为 video_repainting

视频重绘支持从输入视频中提取主体姿态与动作、构图与运动轮廓以及线稿结构,结合文本提示词(prompt),生成具有相同动态特征的新视频。同时,还支持通过参考图像替换原视频中的主体,例如更换角色形象但仍保留原有动作。

video_url string (必选)

输入视频的URL地址。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS。

  • 视频大小:不超过50MB。

  • 视频长度:不超过5秒,否则取视频的前5秒。

  • URL地址中不能包含中文字符。

关于输出视频的分辨率:

  • 若输入视频分辨率 ≤ 720P,输出将保留原始分辨率;

  • 若输入视频分辨率 > 720P,则在保持原视频宽高比的前提下,按比例缩放至不超过 720P。

关于输出视频的时长:

  • 输出视频时长与输入视频一致,最长不超过 5 秒。

  • 示例:若输入视频为 3 秒,则输出也为 3 秒;若输入为 6 秒,则输出为前 5 秒。

ref_images_url array[string] (可选)

输入参考图像的 URL数组。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

仅支持传入1参考图像,且该图像建议为主体图像,用于替换输入视频中的主体内容。

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽度和高度范围为[360, 2000],单位为像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

使用建议:

  • 若使用参考图像中的主体时,建议每张图像仅包含一个主体。背景建议为纯色(如白色或单一颜色),以便更好地突出主体。

parameters object (必选)

视频处理参数,如设置水印等。

属性

control_condition string (必选)

设置视频特征提取的方式。

  • posebodyface:提取输入视频中主体的脸部表情和肢体动作,适用于需保留主体表情细节的场景。

  • posebody:提取输入视频中主体的肢体动作(不含脸部表情),适用于只需要控制主体身体动作的场景。

  • depth:提取输入视频的构图和运动轮廓。

  • scribble:提取输入视频的线稿结构。

strength float (可选)

调节 control_condition 所指定的视频特征提取方式对生成视频的控制强度。

默认值为1.0,取值范围[0.0, 1.0]。

数值越大,生成视频越贴近原视频动作和构图;数值越小,生成内容越自由。

prompt_extend bool (可选)

是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。

  • false(默认值):关闭智能改写。(推荐)

  • true:开启智能改写。

当文本描述与输入的视频内容不一致时,模型可能产生误解。建议关闭智能扩写,并在 prompt 中提供清晰、具体的画面描述,以提升生成一致性与准确性。

seed integer (可选)

随机数种子,用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

watermark bool (可选)

是否添加水印标识,水印位于图片右下角,文案为“AI生成”。

  • false(默认值):不添加水印。

  • true:添加水印。

局部编辑

model string (必选)

模型名称。示例值:wanx2.1-vace-plus

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

提示词,用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

提示词技巧请参见文生视频/图生视频Prompt指南

function string (必选)

功能名称。局部编辑设置为 video_edit

局部编辑支持对输入视频的指定区域进行增加、修改或删除元素,还可以对编辑区域的主体或背景进行替换,实现精细化的视频编辑。

video_url string (必选)

输入视频的URL地址。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS。

  • 视频大小:不超过50MB。

  • 视频长度:不超过5秒,否则取视频的前5秒。

  • URL地址中不能包含中文字符。

关于输出视频的分辨率:

  • 若输入视频分辨率 ≤ 720P,输出将保留原始分辨率;

  • 若输入视频分辨率 > 720P,则在保持原视频宽高比的前提下,按比例缩放至不超过 720P。

关于输出视频的时长:

  • 输出视频时长与输入视频一致,最长不超过 5 秒。

  • 示例:若输入视频为 3 秒,则输出也为 3 秒;若输入为 6 秒,则输出为前 5 秒。

ref_images_url array[string] (可选)

输入参考图像的URL数组。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

当前仅支持传入 1 张 参考图像 ,该图像可作为主体或背景使用,用于替换输入视频中的对应内容。

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽度和高度范围为[360, 2000],单位为像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

使用建议:

  • 若使用参考图像中的主体时,建议每张图像中仅包含一个主体。背景建议为纯色(如白色或单一颜色),以便更好地突出主体。

  • 若使用参考图像的背景时,背景图像中不包含任何主体对象。

mask_image_url string (可选)

掩码图像的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

该参数用于指定视频的编辑区域。与 mask_video_url 参数二选一填写,推荐优先使用此参数

掩码图像的白色区域(像素值严格为 [255, 255, 255])表示需要编辑的部分;黑色区域(像素值严格为 [0, 0, 0])表示保留不变的区域。

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:和输入视频(video_url)分辨率严格相同。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

mask_frame_id integer (可选)

mask_image_url 不为空时,该参数生效,用于标识掩码目标出现在视频中的哪一帧,以“帧 ID”表示。

默认值为 1,单位为帧,表示视频的第一帧(首帧)。

取值范围为[1, max_frame_id],其中max_frame_id=输入视频帧率*输入视频时长+1

例如,输入视频(video_url)帧率为16FPS,表示每秒 16 帧,视频时长为5秒,因此输入视频的总帧数为16*5+1=81,即max_frame_id=81。

mask_video_url string (可选)

掩码视频的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

该参数用于指定视频的编辑区域。与mask_image_url参数,二选一填写。

掩码视频的视频格式、帧率、分辨率、长度需与输入视频(video_url)完全一致。

掩码视频的白色区域(像素值严格为 [255, 255, 255])表示需要编辑的部分;黑色区域(像素值严格为 [0, 0, 0])表示保留不变的区域。

parameters object (可选)

视频处理参数,如设置水印等。

属性

control_condition string (可选)

设置视频特征提取的方式。默认为"",表示不做任何提取。

  • posebodyface:提取输入视频的主体的脸部表情和肢体动作,适用于主体脸部在画面中占比较大、特征清晰可见的场景。

  • depth:提取输入视频的构图和运动轮廓。

mask_type string (可选)

mask_image_url 不为空时,该参数生效,用于指定编辑区域的行为方式。

  • tracking(默认值):编辑区域将根据目标物体的运动轨迹动态跟随,适用于主体运动场景。

  • fixed :编辑区域保持固定不变,不会随画面内容变化。

expand_ratio float (可选)

mask_typetracking 时,该参数生效,表示对掩码区域进行向外扩展的比例。

取值范围为 [0.0, 1.0],默认值为 0.05。推荐使用默认值。

取值越小,掩码区域越贴合目标物体;取值越大,掩码区域的扩展范围越广。

expand_mode string (可选)

mask_typetracking 时,该参数生效,表示掩码区域的形状。

算法会根据选择的expand_mode,基于输入的掩码图像生成对应形状的掩码视频。支持的取值如下:

  • hull(默认值):多边形模式,表示使用一个多边形包裹掩码目标。

  • bbox:边界框模式,表示使用一个矩形包裹掩码目标。

  • original:原始模式,表示尽量保持与原始掩码目标的形状一致。

size string (可选)

生成视频的分辨率(宽*高)。目前支持生成720P 视频,分辨率的取值为:

  • 1280*720(默认值):视频宽高比为16:9。其中,1280代表宽度,720代表高度。

  • 720*1280:视频宽高比为9:16。

  • 960*960:视频宽高比为1:1。

  • 832*1088:视频宽高比为3:4。

  • 1088*832:视频宽高比为4:3。

duration integer (可选)

视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。

prompt_extend bool (可选)

是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。

  • false(默认值):关闭智能改写。(推荐)

  • true:开启智能改写。

当文本描述与输入的视频内容不一致时,模型可能产生误解。建议关闭智能扩写,并在 prompt 中提供清晰、具体的画面描述,以提升生成一致性与准确性。

seed integer (可选)

随机数种子,用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

watermark bool (可选)

是否添加水印标识,水印位于图片右下角,文案为“AI生成”。

  • false(默认值):不添加水印。

  • true:添加水印。

视频延展

model string (必选)

模型名称。示例值:wanx2.1-vace-plus

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

提示词,用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

提示词技巧请参见文生视频/图生视频Prompt指南

function string (必选)

功能名称。视频延展设置为 video_extension

视频延展支持基于图像或视频生成延续性内容,还支持通过参考视频提取动态特征(如动作、构图等),用于指导生成具有相似运动表现的视频。

延长后的视频总时长为 5 秒 ,请注意:这是指最终输出视频的完整时长为 5 秒,而非在原视频基础上延长 5 秒。

first_frame_url string (可选)

首帧图像的URL地址。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽和高范围在[360, 2000],单位像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

last_frame_url string(可选)

尾帧图像的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

图像限制:

  • 图像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率:图像的宽和高范围在[360, 2000],单位像素。

  • 图像大小:不超过10MB。

  • URL地址中不能包含中文字符。

first_clip_url string (可选)

首段视频的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS。当first_clip_urllast_clip_url同时使用时,建议两个片段的帧率保持一致。

  • 视频大小:不超过50MB。

  • 视频长度:不超过3秒,否则取视频的前3秒。若同时填写first_clip_urllast_clip_url时,两段视频的总时长不超过3秒。

  • URL地址中不能包含中文字符。

关于输出视频的分辨率:

  • 若输入视频分辨率 ≤ 720P,输出将保留原始分辨率;

  • 若输入视频分辨率 > 720P,则在保持原视频宽高比的前提下,按比例缩放至不超过 720P。

last_clip_url string(可选)

尾段视频的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS。当first_clip_urllast_clip_url同时使用时,建议两个片段的帧率保持一致。

  • 视频大小:不超过50MB。

  • 视频长度:不超过3秒,否则取视频的前3秒。若同时填写first_clip_urllast_clip_url时,两段视频的总时长不超过3秒。

  • URL地址中不能包含中文字符。

关于输出视频的分辨率:

  • 若输入视频分辨率 ≤ 720P,输出将保留原始分辨率;

  • 若输入视频分辨率 > 720P,则在保持原视频宽高比的前提下,按比例缩放至不超过 720P。

video_url string (可选)

输入视频的URL地址。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

该视频主要用于提取其中的运动特征,与 first_frame_urllast_frame_urlfirst_clip_urllast_clip_url参数配合使用,以指导生成具有相似运动表现的延展视频。

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS,与前后片段保持一致。

  • 视频分辨率:与前后帧、前后片段保持一致。

  • 视频大小:不超过50MB。

  • 视频长度:不超过5秒,否则取视频的前5秒。

  • URL地址中不能包含中文字符。

parameters object (可选)

视频处理参数,如设置输出视频的分辨率等。

属性

control_condition string (可选)

设置视频特征提取的方式,输入video_url时必选。默认为"",表示不做任何提取。

  • posebodyface:提取输入视频的主体的脸部表情和肢体动作。

  • depth:提取输入视频的构图和运动轮廓。

duration integer (可选)

视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。

prompt_extend bool (可选)

是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。

  • false(默认值):关闭智能改写。(推荐)

  • true:开启智能改写。

当文本描述与输入的视频内容不一致时,模型可能产生误解。建议关闭智能扩写,并在 prompt 中提供清晰、具体的画面描述,以提升生成一致性与准确性。

seed integer (可选)

随机数种子,用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

watermark bool (可选)

是否添加水印标识,水印位于图片右下角,文案为“AI生成”。

  • false(默认值):不添加水印。

  • true:添加水印。

视频画面扩展

model string (必选)

模型名称。示例值:wanx2.1-vace-plus

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

提示词,用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。

提示词技巧请参见文生视频/图生视频Prompt指南

function string (必选)

功能名称。视频画面扩展设置为 video_outpainting

视频画面扩展支持对视频在上、下、左、右四个方向按比例扩展。

video_url string (必选)

输入视频的URL地址。

URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL

视频限制:

  • 视频格式:MP4。

  • 视频帧率:大于等于16FPS。

  • 视频大小:不超过50MB。

  • 视频长度:不超过5秒,否则取视频的前5秒。

  • URL地址中不能包含中文字符。

关于输出视频的分辨率:

  • 若输入视频分辨率 ≤ 720P,输出将保留原始分辨率;

  • 若输入视频分辨率 > 720P,则在保持原视频宽高比的前提下,按比例缩放至不超过 720P。

关于输出视频的时长:

  • 输出视频时长与输入视频一致,最长不超过 5 秒。

  • 示例:若输入视频为 3 秒,则输出也为 3 秒;若输入为 6 秒,则输出为前 5 秒。

parameters object (可选)

视频处理参数,如设置扩展比例等。

属性

top_scale float (可选)

视频画面居中,向上按比例扩展视频。

取值范围为[1.0, 2.0],默认值为1.0,表示不扩展。

bottom_scale float (可选)

视频画面居中,向下按比例扩展视频。

取值范围为[1.0, 2.0],默认值为1.0,表示不扩展。

left_scale float (可选)

视频画面居中,向左按比例扩展视频。

取值范围为[1.0, 2.0],默认值为1.0,表示不扩展。

right_scale float (可选)

视频画面居中,向右按比例扩展视频。

取值范围为[1.0, 2.0],默认值为1.0,表示不扩展。

duration integer (可选)

视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。

prompt_extend bool (可选)

是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。

  • false(默认值):关闭智能改写。(推荐)

  • true:开启智能改写。

当文本描述与输入的视频内容不一致时,模型可能产生误解。建议关闭智能扩写,并在 prompt 中提供清晰、具体的画面描述,以提升生成一致性与准确性。

seed integer (可选)

随机数种子,用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]

如果不提供,则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定,请使用相同的seed参数值。

watermark bool (可选)

是否添加水印标识,水印位于图片右下角,文案为“AI生成”。

  • false(默认值):不添加水印。

  • true:添加水印。

响应参数

成功响应

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

异常响应

模型调用失败,请参见错误信息进行解决。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务ID。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务取消成功

  • UNKNOWN:任务不存在或状态未知

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

步骤2:根据任务ID查询结果

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

请求参数

查询任务结果

您需要将86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
请求头(Headers)

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

URL路径参数(Path parameters)

task_id string(必选)

任务ID。

响应参数

任务执行成功

任务数据(如任务状态、视频URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的视频。

{
    "request_id": "851985d0-fbba-9d8d-a17a-xxxxxx",
    "output": {
        "task_id": "208e2fd1-fcb4-4adf-9fcc-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-05-15 16:14:44.723",
        "scheduled_time": "2025-05-15 16:14:44.750",
        "end_time": "2025-05-15 16:20:09.389",
        "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx",
        "orig_prompt": "视频中,一位女孩自晨雾缭绕的古老森林深处款款走出,她步伐轻盈,镜头捕捉她每一个灵动瞬间。当女孩站定,环顾四周葱郁林木时,她脸上绽放出惊喜与喜悦交织的笑容。这一幕,定格在了光影交错的瞬间,记录下女孩与大自然的美妙邂逅。",
        "actual_prompt": "一位身着浅色长裙的女孩从晨雾缭绕的古老森林深处缓缓走出,步伐轻盈如舞。她长发微卷,面容清秀,眼神明亮。镜头跟随她的动作,捕捉每一个灵动瞬间。当她站定,转身环顾四周葱郁林木时,脸上绽放出惊喜与喜悦交织的笑容。阳光透过树叶洒下斑驳光影,定格这一人与自然和谐共处的美好时刻。画面风格为清新自然系写真,中景全景结合,平视视角带有轻微移动运镜。"
    },
    "usage": {
        "video_duration": 5,
        "video_ratio": "standard",
        "video_count": 1
    }
}

任务执行失败

如果因为某种原因导致任务执行失败,任务状态将被设置为FAILED,并通过codemessage字段明确指示错误原因。请参见错误信息进行解决。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

output object

任务输出信息。

属性

task_id string

任务ID。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务取消成功

  • UNKNOWN:任务不存在或状态未知

submit_time string

任务提交时间。

scheduled_time string

任务执行时间。

end_time string

任务完成时间。

video_url string

视频URL。链接有效期24小时,可通过此URL下载视频。

orig_prompt string

原始的输入prompt。

actual_prompt string

开启prompt智能改写后实际使用的prompt。若不开启prompt智能改写,不会返回该字段。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

usage object

输出信息统计。只对成功的结果计数。

属性

video_duration integer

生成视频的时长,单位为秒。

video_ratio string

生成视频的比例。固定为standard

video_count integer

生成视频的数量。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

错误码

如果模型调用失败并返回报错信息,请参见错误信息进行解决。

API还有特定状态码,具体如下所示。

HTTP状态码

接口错误码(code)

接口错误信息(message)

含义说明

400

InvalidParameter

InvalidParameter

请求参数不合法。

400

IPInfringementSuspect

Input data is suspected of being involved in IP infringement.

输入数据(如提示词或图像)涉嫌知识产权侵权。请检查输入,确保不包含引发侵权风险的内容。

400

DataInspectionFailed

Input data may contain inappropriate content.

输入数据(如提示词或图像)可能包含敏感内容。请修改输入后重试。

500

InternalError

InternalError

服务异常。请先尝试重试,排除偶发情况。

视频访问配置

配置域名白名单:确保业务系统可访问视频链接

模型生成的视频存储于阿里云OSS,每个视频会被分配一个OSS链接,如https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.mp4。OSS链接允许公开访问,您可以使用此链接下载视频,链接仅在 24 小时内有效。

特别注意的是,如果您的业务对安全性要求较高,无法访问阿里云OSS链接,您需要单独配置外网访问白名单。请将以下域名添加到您的白名单中,以便顺利访问视频链接。

# OSS域名列表
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com