万相2.7-图生视频模型全新升级,支持 多模态输入 (文本/图像/音频/视频),可完成 首帧生视频、首尾帧生视频、视频续写 三大任务。
相关文档:使用指南
为确保调用成功,请务必保证模型、endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
图生视频任务耗时较长(通常为1-5分钟),API采用异步调用的方式。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤,具体如下:
调用时请将
调用时请将
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
根据模型所在地域设置
调用时请将
根据模型所在地域设置
调用时请将
如果模型调用失败并返回报错信息,请参见错误码进行解决。
A: 输出视频的宽高比由 输入素材(首帧图像或首视频片段)决定,但无法保证严格等于输入比例(如精确 3:4),实际输出会存在微小偏差。
下面以“输入首帧图像”为例说明具体逻辑:
A: 模型生成的视频存储于阿里云OSS,API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置,请注意:由于底层存储会根据业务情况进行动态变更,为避免过期信息影响访问,文档不提供固定的OSS域名白名单。如有安全管控需求,请联系客户经理获取最新OSS域名列表。
全新推出的图生视频 API(wan2.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。
请求参数Content-Typestring(必选)请求内容类型。此参数必须设置为application/json。Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable。请求体(Request Body)modelstring (必选)模型名称。模型列表与价格详见模型价格。示例值:wan2.7-i2v-2026-04-25。input object (必选)输入的基本信息,如提示词等。
属性 prompt string (可选)文本提示词。用来描述生成视频中期望包含的元素和视觉特点。支持中英文,长度不超过5000个字符。每个汉字/字母占一个字符,超过部分会自动截断。示例值:一只小猫在草地上奔跑。提示词使用技巧详见文生视频/图生视频Prompt指南。negative_prompt string (可选)反向提示词,用来描述不希望在视频画面中看到的内容,可以对视频画面进行限制。支持中英文,长度不超过500个字符,超过部分会自动截断。示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。media array (必选)媒体素材列表,用于指定视频生成所需的参考素材(图像、音频和视频)。数组的每个元素为一个媒体对象,包含 type 与 url 字段。
素材组合 仅支持以下特定的素材组合,非法组合将报错。
属性 type string (必选)媒体素材类型。可选值为:
type 在 media 数组中最多出现一次(例如:不可同时传入两个 first_frame)。url string (必选)媒体素材URL。素材包括图像、音频和视频。
传入图像(type=first_frame或last_frame) 首帧或尾帧URL,或 Base64 编码数据。目前支持首帧生视频、首尾帧生视频。图像限制:
传入音频(type=driving_audio) 音频文件的 URL。
传入视频(type=first_clip) 视频文件的 URL。模型将基于该视频内容进行续写生成,续写时长的上限由 duration 参数控制。例如:当duration=15时,输入视频 3 秒,则模型续写生成 12 秒,最终输出视频总时长 15 秒, 按 15 秒计费。视频限制:
object (可选)视频处理参数,如设置视频分辨率、设置视频时长、开启prompt智能改写、添加水印等。
属性 resolution string (可选)指定生成的视频分辨率档位,用于控制视频的清晰度(总像素)。模型根据选择的分辨率档位,自动缩放至相近总像素。视频宽高比尽量与输入素材(首帧或首段视频)保持一致,详见常见问题。可选值:
integer (可选)生成视频的时长,单位为秒。取值为[2, 15]之间的整数。默认值为5。prompt_extendboolean (可选)是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。
boolean (可选)是否添加水印标识,水印位于视频右下角,文案固定为“AI生成”。
integer(可选)随机数种子,取值范围为[0, 2147483647]。未指定时,系统自动生成随机种子。若需提升生成结果的可复现性,建议固定seed值。请注意,由于模型生成具有概率性,即使使用相同 seed,也不能保证每次生成结果完全一致。 |
基于首帧图像和音频生成视频。 |
响应参数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。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。object输出信息统计,只对成功的结果计数。
属性 input_video_duration integer输入的视频的时长,单位秒。output_video_duration integer输出视频的时长,单位秒。duration integer总的视频时长,用于计费。SR integer输出视频的分辨率档位。示例值:720。video_count integer输出视频的数量。固定为1。string请求唯一标识。可用于请求明细溯源和问题排查。 |
视频URL仅保留24小时,超时后会被自动清除,请及时保存生成的视频。 |
DashScope SDK调用
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
具体耗时受限于排队任务数和服务执行情况,请在获取结果时耐心等待。
Python SDK调用
根据模型所在地域设置 dashscope.base_http_api_url:
- 北京
- 新加坡
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'{WorkspaceId}替换为真实的业务空间ID。
- 同步调用
- 异步调用
请求示例
响应示例
video_url 有效期24小时,请及时下载视频。
Java SDK调用
根据模型所在地域设置 Constants.baseHttpApiUrl:
- 北京
- 新加坡
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"{WorkspaceId}替换为真实的业务空间ID。
- 同步调用
- 异步调用
同步调用会阻塞等待,直到视频生成完成并返回结果。
请求示例
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。
常见问题
Q:如何生成特定宽高比(如3:4)的视频?
A: 输出视频的宽高比由 输入素材(首帧图像或首视频片段)决定,但无法保证严格等于输入比例(如精确 3:4),实际输出会存在微小偏差。
下面以“输入首帧图像”为例说明具体逻辑:
-
为什么会有偏差?
- 执行逻辑:以输入图像的比例为基准比例参考,结合
resolution档位的目标总像素,且视频长宽必须为 16 的倍数(视频编码规范),系统会自动微调至最接近的合法分辨率。 - 计算示例:输入首帧图像750×1000(宽高比 3:4 = 0.75),并设置 resolution = "720P"(目标总像素约 92 万),实际输出视频的分辨率为816×1104(宽高比 ≈ 0.739,总像素约90万)。
- 执行逻辑:以输入图像的比例为基准比例参考,结合
-
实践建议:
- 输入控制:尽量使用与目标比例一致的首帧或首视频片段作为输入。
- 后期处理:如果您对比例有严格要求,建议在视频生成后,使用编辑工具进行简单的裁剪或黑边填充。