万相-图生视频模型根据 首帧图像 和 文本提示词 ,生成一段流畅的视频。
相关文档:使用指南
为确保调用成功,请务必保证模型、endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
图生视频任务耗时较长(通常为1-5分钟),API采用异步调用的方式。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤,具体如下:
调用时请将
调用时请将
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
根据模型所在地域设置
调用时请将
根据模型所在地域设置
调用时请将
使用 wan2.6-i2v-flash 生成圆形物体连续旋转(如圆环、齿轮、表盘)的动画时,画面在约 3 秒后可能出现短暂卡顿(画面静止约 1 秒)。如需生成此类连续旋转效果,建议改用万相2.7-图生视频模型以规避此问题。
如果模型调用失败并返回报错信息,请参见错误码进行解决。
A: 输出视频的宽高比由输入首帧图像(img_url)决定,但无法保证精确比例(如严格3:4),会存在一定偏差。
A: 模型生成的视频存储于阿里云OSS,API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置,请注意:由于底层存储会根据业务情况进行动态变更,为避免过期信息影响访问,文档不提供固定的OSS域名白名单。如有安全管控需求,请联系客户经理获取最新OSS域名列表。
全新推出的万相2.7-图生视频支持首帧生视频、首尾帧生视频、视频续写三大任务,推荐优先选用。本文档的图生视频-基于首帧(wan2.6及早期模型)仅支持首帧生视频。
适用范围
为确保调用成功,请务必保证模型、endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
- 选择模型:确认模型所属的地域。
- 选择 URL:选择对应的地域 Endpoint URL,支持HTTP URL或 DashScope SDK URL。
- 配置 API Key:获取该地域的API Key,再配置API Key到环境变量。
- 安装 SDK:如需通过SDK进行调用,请安装DashScope SDK。
本文的示例代码适用于北京地域。
HTTP调用
图生视频任务耗时较长(通常为1-5分钟),API采用异步调用的方式。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤,具体如下:
步骤1:创建任务获取任务ID
- 北京
- 新加坡
- 弗吉尼亚
- 法兰克福
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId}替换为真实的业务空间ID。
- 创建成功后,使用接口返回的
task_id查询结果,task_id 有效期为 24 小时。请勿重复创建任务,轮询获取即可。 - 新手指引请参见Postman。
请求参数请求头(Headers)Content-Typestring(必选)请求内容类型。此参数必须设置为application/json。Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable。请求体(Request Body)modelstring (必选)模型名称。模型列表与价格详见模型价格。示例值:wan2.6-i2v-flash。input object (必选)输入的基本信息,如提示词等。
属性 prompt string (可选)文本提示词。用来描述生成图像中期望包含的元素和视觉特点。支持中英文,每个汉字/字母占一个字符,超过部分会自动截断。长度限制因模型版本而异:
template不为空)时,prompt参数无效,无需填写。示例值:一只小猫在草地上奔跑。提示词使用技巧详见文生视频/图生视频Prompt指南。negative_prompt string (可选)反向提示词,用来描述不希望在视频画面中看到的内容,可以对视频画面进行限制。支持中英文,长度不超过500个字符,超过部分会自动截断。示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。img_url string (必选)首帧图像的URL或 Base64 编码数据。图像限制:
string (可选)支持模型:wan2.6和wan2.5系列模型。音频文件的 URL,模型将使用该音频生成视频。支持输入的格式:
string (可选)视频特效模板的名称。若未填写,表示不使用任何视频特效。不同模型支持不同的特效模板。调用前请查阅万相-图生视频-视频特效列表,以免调用失败。示例值:flying,表示使用“魔法悬浮”特效。object (可选)视频处理参数,如设置视频分辨率、设置视频时长、开启prompt智能改写、添加水印等。
属性 resolution string (可选)指定生成的视频分辨率档位,用于调整视频的清晰度(总像素)。模型根据选择的分辨率档位,自动缩放至相近总像素,视频宽高比将尽量与输入图像 img_url 的宽高比保持一致,详见常见问题。此参数的默认值和可用枚举值依赖于 model 参数,规则如下:
integer (可选)生成视频的时长,单位为秒。该参数的取值依赖于 model参数:
boolean (可选)是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。
string (可选)支持模型:wan2.6系列模型。指定生成视频的镜头类型,即视频是由一个连续镜头还是多个切换镜头组成。生效条件:仅当"prompt_extend": true 时生效。参数优先级:shot_type > prompt。例如,若 shot_type设置为"single",即使 prompt 中包含“生成多镜头视频”,模型仍会输出单镜头视频。可选值:
当希望严格控制视频的叙事结构(如产品展示用单镜头、故事短片用多镜头),可通过此参数指定。 boolean (可选)支持模型:wan2.6-i2v-flash。是否生成有声视频。参数优先级:audio > audio_url。当 audio=false时,即使传入 audio_url,输出仍为无声视频,且计费按无声视频计算。可选值:
boolean (可选)是否添加水印标识,水印位于视频右下角,文案固定为“AI生成”。
integer(可选)随机数种子,取值范围为[0, 2147483647]。未指定时,系统自动生成随机种子。若需提升生成结果的可复现性,建议固定seed值。请注意,由于模型生成具有概率性,即使使用相同 seed,也不能保证每次生成结果完全一致。示例值:12345。 |
仅wan2.6系列模型支持此功能。可通过设置 "prompt_extend": true和"shot_type":"multi"启用。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。 |
请保存 task_id,用于查询任务状态与结果。 |
步骤2:根据任务ID查询结果
- 北京
- 新加坡
- 弗吉尼亚
- 法兰克福
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId}替换为真实的业务空间ID。
请求参数请求头(Headers)Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。URL路径参数(Path parameters)task_idstring(必选)任务ID。 |
将 {task_id}完整替换为上一步接口返回的task_id的值。task_id查询有效期为24小时,并请将{WorkspaceId}替换为真实的业务空间ID。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。end_time string任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。video_urlstring视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时,可通过此URL下载视频。视频格式为MP4(H.264 编码)。orig_prompt string原始输入的prompt,对应请求参数prompt。actual_prompt string当 prompt_extend=true 时,系统会对输入 prompt 进行智能改写,此字段返回实际用于生成的优化后 prompt。
string请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。object输出信息统计,只对成功的结果计数。
属性
wan2.6系列模型返回参数 input_video_duration integer输入的视频的时长,单位秒。当前不支持传入视频,因此固定为0。output_video_duration integer仅在使用 wan2.6 模型时返回。输出视频的时长,单位秒。其值等同于input.duration的值。duration integer总的视频时长,用于计费。计费公式:duration=input_video_duration+output_video_duration。SR integer仅在使用 wan2.6 模型时返回。生成视频的分辨率档位。示例值:720。video_count integer生成视频的数量。固定为1。audioboolean仅在使用wan2.6-i2v-flash模型时返回。表示输出视频是否为有声视频。
wan2.2和wan2.5系列模型返回参数 duration integer生成视频的时长,单位为秒。枚举值为5、10。计费公式:费用 = 视频秒数 × 单价。SR integer生成视频的分辨率。枚举值为480、720、1080。video_count integer生成视频的数量。固定为1。
wan2.1系列模型返回参数 video_duration integer生成视频的时长,单位为秒。枚举值为3、4、5。计费公式:费用 = 视频秒数 × 单价。video_ratio string生成视频的比例。固定为standard。video_count integer生成视频的数量。固定为1。string请求唯一标识。可用于请求明细溯源和问题排查。 |
视频URL仅保留24小时,超时后会被自动清除,请及时保存生成的视频。 |
DashScope SDK调用
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
具体耗时受限于排队任务数和服务执行情况,请在获取结果时耐心等待。
Python SDK调用
根据模型所在地域设置 base_http_api_url:
- 北京
- 新加坡
- 弗吉尼亚
- 法兰克福
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'{WorkspaceId}替换为真实的业务空间ID。
示例代码
- 同步调用
- 异步调用
同步调用会阻塞等待,直到视频生成完成并返回结果。本示例展示三种图像输入方式:公网URL、Base64编码、本地文件路径。
请求示例
响应示例
video_url 有效期24小时,请及时下载视频。
Java SDK调用
根据模型所在地域设置 baseHttpApiUrl:
- 北京
- 新加坡
- 弗吉尼亚
- 法兰克福
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";{WorkspaceId}替换为真实的业务空间ID。
示例代码
- 同步调用
- 异步调用
同步调用会阻塞等待,直到视频生成完成并返回结果。本示例展示三种图像输入方式:公网URL、Base64编码、本地文件路径。
请求示例
响应示例
video_url 有效期24小时,请及时下载视频。
使用限制
- 数据时效:任务task_id和 视频url均只保留 24 小时,过期后将无法查询或下载。
- 内容审核:输入的内容(如prompt、图像)、输出视频均会经过内容安全审核,含违规内容将返回 “IPInfringementSuspect”或“DataInspectionFailed”错误,详见参见错误码。
已知限制
使用 wan2.6-i2v-flash 生成圆形物体连续旋转(如圆环、齿轮、表盘)的动画时,画面在约 3 秒后可能出现短暂卡顿(画面静止约 1 秒)。如需生成此类连续旋转效果,建议改用万相2.7-图生视频模型以规避此问题。
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。
常见问题
Q:如何生成特定宽高比(如3:4)的视频?
A: 输出视频的宽高比由输入首帧图像(img_url)决定,但无法保证精确比例(如严格3:4),会存在一定偏差。
-
为什么会有偏差?
模型会以输入图像的比例为基准,结合设置的分辨率档位(resolution)总像素,自动计算出最接近的合法分辨率。由于要求视频的长和宽必须是 16 的倍数,模型会对最终分辨率做微调,因此无法保证输出比例严格等于 3:4,但会非常接近。
- 例如:输入图像750×1000(宽高比 3:4 = 0.75),并设置 resolution = "720P"(目标总像素约 92 万),实际输出816×1104(宽高比 ≈ 0.739,总像素约90万)。
-
实践建议:
- 输入控制:尽量使用与目标比例一致的图片作为首帧输入。
- 后期处理:如果您对比例有严格要求,建议在视频生成后,使用编辑工具进行简单的裁剪或黑边填充。