万相2.2-首尾帧生视频模型基于 首帧图像 、 尾帧图像和文本提示词 ,生成一段平滑过渡的视频。
相关文档:使用指南
为确保调用成功,请务必保证模型、Endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
由于图生视频任务耗时较长(通常为1-5分钟),API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤,具体如下:
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
根据模型所在地域设置
如果模型调用失败并返回报错信息,请参见错误码进行解决。
A: 输出视频的宽高比由输入首帧图像(first_frame_url)决定,但无法保证精确比例(如严格3:4),会存在一定偏差。
A: 模型生成的视频存储于阿里云OSS,API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置,请注意:由于底层存储会根据业务情况进行动态变更,为避免过期信息影响访问,文档不提供固定的OSS域名白名单。如有安全管控需求,请联系客户经理获取最新OSS域名列表。
适用范围
为确保调用成功,请务必保证模型、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}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/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.2-kf2v-flash。详情参见百炼控制台。input object (必选)输入的基本信息,如提示词等。
属性 prompt string (可选)文本提示词。支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。如果首尾帧的主体和场景变化较大,建议描写变化过程,例如运镜过程(镜头向左移动)或者主体运动过程(人向前奔跑)。示例值:一只黑色小猫好奇地看向天空,镜头从平视逐渐上升,最后俯拍它的好奇的眼神。提示词的使用技巧请参见文生视频/图生视频Prompt指南。negative_prompt string (可选)反向提示词,用来描述不希望在视频画面中看到的内容,可以对视频画面进行限制。支持中英文,长度不超过500个字符,超过部分会自动截断。示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。first_frame_url string (必选)首帧图像URL。输出视频的宽高比与首帧图像保持一致。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。图像限制:
string (必选)尾帧图像URL。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。图像限制:
object (可选)视频处理参数。
属性 resolution string (可选)生成的视频分辨率档位。仅用于调整视频的清晰度(总像素),不改变视频的宽高比,视频宽高比将与首帧图像 first_frame_url 的宽高比保持一致。此参数的默认值和可用枚举值依赖于 model 参数,规则如下:
integer (可选)视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。prompt_extendbool (可选)是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。
bool (可选)是否添加水印标识,水印位于图片右下角,文案为“AI生成”。
integer(可选)随机数种子,取值范围为[0, 2147483647]。未指定时,系统自动生成随机种子。若需提升生成结果的可复现性,建议固定seed值。请注意,由于模型生成具有概率性,即使使用相同 seed,也不能保证每次生成结果完全一致。 |
根据首帧、尾帧和prompt生成视频。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。 |
请保存 task_id,用于查询任务状态与结果。 |
步骤2:根据任务ID查询结果
- 新加坡
- 北京
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}调用时请将{WorkspaceId}替换为真实的业务空间ID。- 轮询建议:视频生成过程约需数分钟,建议采用轮询机制,并设置合理的查询间隔(如 15 秒)来获取结果。
- 任务状态流转:PENDING(排队中)→ RUNNING(处理中)→ SUCCEEDED(成功)/ FAILED(失败)。
- 结果链接:任务成功后返回视频链接,有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储(如阿里云 OSS)。
- task_id 有效期:24小时,超时后将无法查询结果,接口将返回任务状态为
UNKNOWN。
请求参数请求头(Headers)Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。URL路径参数(Path parameters)task_idstring(必选)任务ID。 |
请将 86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。各地域的API Key不同。获取与配置 API Key。 若使用华北2(北京)地域的模型,需将base_url替换为https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx,其中{WorkspaceId}需替换为真实的业务空间ID。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string任务提交时间。时区为UTC+8,格式为 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任务执行时间。时区为UTC+8,格式为 YYYY-MM-DD HH:mm:ss.SSS。end_time string任务完成时间。时区为UTC+8,格式为 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 智能改写后,返回实际使用的优化后 prompt。若未开启该功能,则不返回此字段。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。object输出信息统计。只对成功的结果计数。
属性 video_duration integer生成视频的时长,单位秒。枚举值为5。计费公式:费用 = 视频秒数 × 单价。video_count integer生成视频的数量。固定为1。video_ratio string当前仅当2.1模型返回该值。生成视频的比例,固定为standard。SR integer当前仅当2.2模型返回该值。生成视频的分辨率档位,枚举值为480、720、1080。string请求唯一标识。可用于请求明细溯源和问题排查。 |
视频URL仅保留24小时,超时后会被自动清除,请及时保存生成的视频。 |
DashScope SDK调用
SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。
由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
具体耗时受限于排队任务数和服务执行情况,请在获取结果时耐心等待。
Python SDK调用
根据模型所在地域设置 base_http_api_url:
- 新加坡
- 北京
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'调用时请将{WorkspaceId}替换为真实的业务空间ID。示例代码
- 同步调用
- 异步调用
本示例展示同步调用方式,包括两种图像输入方式:公网URL、本地文件路径。
请求示例
响应示例
video_url 有效期24小时,请及时下载视频。
Java SDK调用
示例代码
- 同步调用
- 异步调用
本示例展示同步调用方式,包括两种图像输入方式:公网URL、本地文件路径。
请求示例
响应示例
video_url 有效期24小时,请及时下载视频。
使用限制
- 数据时效:任务
task_id和 视频video_url均只保留 24 小时,过期后将无法查询或下载。 - 音频支持:当前仅支持生成无声视频,不支持音频输出。如有需要,可通过语音合成生成音频。
- 内容审核:输入prompt 和图像、输出视频均会经过内容安全审核,含违规内容将返回 “IPInfringementSuspect”或“DataInspectionFailed”错误,详情请参见错误码。
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。
常见问题
Q:如何生成特定宽高比(如3:4)的视频?
A: 输出视频的宽高比由输入首帧图像(first_frame_url)决定,但无法保证精确比例(如严格3:4),会存在一定偏差。
-
为什么会有偏差?
模型会以输入图像的比例为基准,结合设置的分辨率档位(resolution)总像素,自动计算出最接近的合法分辨率。由于要求视频的长和宽必须是 16 的倍数,模型会对最终分辨率做微调,因此无法保证输出比例严格等于 3:4,但会非常接近。
- 例如:输入图像750×1000(宽高比 3:4 = 0.75),并设置 resolution = "720P"(目标总像素约 92 万),实际输出816×1104(宽高比 ≈ 0.739,总像素约90万)。
-
实践建议:
- 输入控制:尽量使用与目标比例一致的图片作为首帧输入。
- 后期处理:如果您对比例有严格要求,建议在视频生成后,使用编辑工具进行简单的裁剪或黑边填充。