通义万相Wan首尾帧生视频API参考 - 大模型服务平台百炼

通义万相首尾帧生视频模型基于首帧图像、尾帧图像和文本提示词，生成一段平滑过渡的视频。支持的能力包括：

视频规格：视频时长固定为5秒，视频分辨率固定为720P。
智能 Prompt 优化：自动对输入提示词进行改写，尤其对简短提示词效果提升显著。
其他：可选择是否添加“AI生成”水印。

说明

通义万相官网的功能与API支持的能力可能存在差异。本文档以API的实际能力为准，并会随功能更新及时同步。

模型概览

模型功能	输入示例			输出视频
模型功能	首帧图片	尾帧图片	提示词	输出视频
首尾帧生视频			写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。

模型名称

模型简介

输出视频格式

wan2.1-kf2v-plus

万相2.1专业版（无声视频）

复杂运动，物理规律还原，画面细腻

分辨率档位：720P

视频时长：5秒

固定规格：30fps、MP4（H.264编码）

说明

调用前，请查阅各地域支持的模型列表与价格。

前提条件

在调用前，需要获取API Key，再配置API Key到环境变量。如果通过SDK进行调用，请安装DashScope SDK。目前，该SDK已支持Python和Java。

重要

北京和新加坡地域拥有独立的 API Key 与请求地址，不可混用，跨地域调用将导致鉴权失败或服务报错。

HTTP调用

由于图生视频任务耗时较长（通常为1-5分钟），API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤，具体如下：

具体耗时受限于排队任务数和服务执行情况，请在获取结果时耐心等待。

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

新加坡地域：POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

北京地域：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

说明

创建成功后，使用接口返回的 task_id 查询结果，task_id 有效期为 24 小时。请勿重复创建任务，轮询获取即可。

请求参数	首尾帧生视频根据首帧、尾帧和prompt生成视频。 curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \ -H 'X-DashScope-Async: enable' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "wan2.1-kf2v-plus", "input": { "first_frame_url": "https://wanx.alicdn.com/material/20250318/first_frame.png", "last_frame_url": "https://wanx.alicdn.com/material/20250318/last_frame.png", "prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。" }, "parameters": { "resolution": "480P", "prompt_extend": true } }' 使用反向提示词通过 negative_prompt 指定生成的视频避免出现“人物”元素。 curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \ -H 'X-DashScope-Async: enable' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "wan2.1-kf2v-plus", "input": { "first_frame_url": "https://wanx.alicdn.com/material/20250318/first_frame.png", "last_frame_url": "https://wanx.alicdn.com/material/20250318/last_frame.png", "prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。", "negative_prompt": "人物" }, "parameters": { "resolution": "720P", "prompt_extend": true } }'
请求头（Headers）
Content-Type `string` （必选）请求内容类型。此参数必须设置为`application/json`。
Authorization `string`（必选）请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值：Bearer sk-xxxx。
X-DashScope-Async `string` （必选）异步处理配置参数。HTTP请求只支持异步，必须设置为`enable`。重要缺少此请求头将报错：“current user api does not support synchronous calls”。
请求体（Request Body）
model `string` （必选）模型名称。示例值：wan2.1-kf2v-plus。详情参见模型列表与价格。
input `object` （必选）输入的基本信息，如提示词等。属性 prompt `string` （可选）文本提示词。支持中英文，长度不超过800个字符，每个汉字/字母占一个字符，超过部分会自动截断。如果首尾帧的主体和场景变化较大，建议描写变化过程，例如运镜过程（镜头向左移动）、或者主体运动过程（人向前奔跑）。示例值：一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。提示词的使用技巧请参见文生视频/图生视频Prompt指南。 negative_prompt `string` （可选）反向提示词，用来描述不希望在视频画面中看到的内容，可以对视频画面进行限制。支持中英文，长度不超过500个字符，超过部分会自动截断。示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。 first_frame_url `string` （必选）首帧图像URL。输出视频的宽高比与首帧图像保持一致。 URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。图像限制：图像格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。图像分辨率：图像的宽度和高度范围为[360, 2000]，单位为像素。文件大小：不超过10MB。 last_frame_url `string` （必选）尾帧图像URL。 URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。图像限制：图像格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。图像分辨率：图像的宽度和高度范围为[360, 2000]，单位为像素。尾帧图像分辨率可与首帧不同，无需强制对齐。文件大小：不超过10MB。
parameters `object` （可选）视频处理参数。属性 resolution `string` （可选）重要 resolution直接影响费用，同一模型：1080P > 720P > 480P，调用前请确认模型价格。生成的视频分辨率档位。仅用于调整视频的清晰度（总像素），不改变视频的宽高比，视频宽高比将与首帧图像 first_frame_url 的宽高比保持一致。此参数的默认值和可用枚举值依赖于 model 参数，规则如下： wan2.1-kf2v-plus：可选值：720P。默认值为`720P`。示例值：720P。 duration `integer` （可选）重要 duration直接影响费用，按秒计费，调用前请确认模型价格。视频生成时长，单位为秒。当前参数值固定为5，且不支持修改。模型将始终生成5秒时长的视频。 prompt_extend `bool` （可选）是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显，但会增加耗时。 true：默认值，开启智能改写。 false：不开启智能改写。示例值：true。 watermark `bool` （可选）是否添加水印标识，水印位于图片右下角，文案为“AI生成”。 false：默认值，不添加水印。 true：添加水印。示例值：false。 seed `integer` （可选）随机数种子。取值范围是`[0, 2147483647]`。未指定时，系统自动生成随机种子。若需提升生成结果的可复现性，建议固定seed值。请注意，由于模型生成具有概率性，即使使用相同 seed，也不能保证每次生成结果完全一致。示例值：12345。

响应参数	成功响应请保存 task_id，用于查询任务状态与结果。 `{ "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。查询有效期24小时。 task_status `string` 任务状态。枚举值 PENDING：任务排队中 RUNNING：任务处理中 SUCCEEDED：任务执行成功 FAILED：任务执行失败 CANCELED：任务已取消 UNKNOWN：任务不存在或状态未知
request_id `string` 请求唯一标识。可用于请求明细溯源和问题排查。
code `string` 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。
message `string` 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。

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

新加坡地域：GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

北京地域：GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

说明

轮询建议：视频生成过程约需数分钟，建议采用轮询机制，并设置合理的查询间隔（如 15 秒）来获取结果。
任务状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
结果链接：任务成功后返回视频链接，有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储（如阿里云 OSS）。
task_id 有效期：24小时，超时后将无法查询结果，接口将返回任务状态为UNKNOWN。

请求参数	查询任务结果请将`86ecf553-d340-4e21-xxxxxxxxx`替换为真实的task_id。新加坡和北京地域的API Key不同。获取API Key。以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx `curl -X GET https://dashscope-intl.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": "ec016349-6b14-9ad6-8009-xxxxxx", "output": { "task_id": "3f21a745-9f4b-4588-b643-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-04-18 10:36:58.394", "scheduled_time": "2025-04-18 10:37:13.802", "end_time": "2025-04-18 10:45:23.004", "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxx", "orig_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。", "actual_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。它的黄色眼睛明亮有神，毛发光滑，胡须清晰可见。背景是简单的浅色墙面，突显它的黑色身影。近景特写，强调它的表情变化和眼神细节。" }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } 任务执行失败若任务执行失败，task_status将置为 FAILED，并提供错误码和信息。请参见错误信息进行解决。 `{ "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" } }` 任务查询过期 task_id查询有效期为 24 小时，超时后将无法查询，返回以下报错信息。 `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` 任务输出信息。属性 task_id `string` 任务ID。查询有效期24小时。 task_status `string` 任务状态。枚举值 PENDING：任务排队中 RUNNING：任务处理中 SUCCEEDED：任务执行成功 FAILED：任务执行失败 CANCELED：任务已取消 UNKNOWN：任务不存在或状态未知轮询过程中的状态流转： PENDING（排队中） → RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。初次查询状态通常为 PENDING（排队中）或 RUNNING（处理中）。当状态变为 SUCCEEDED 时，响应中将包含生成的视频url。若状态为 FAILED，请检查错误信息并重试。 submit_time `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_url `string` 视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时，可通过此URL下载视频。视频格式为MP4（H.264 编码）。 orig_prompt `string` 原始输入的prompt，对应请求参数`prompt`。 actual_prompt `string` 开启 prompt 智能改写后，返回实际使用的优化后 prompt。若未开启该功能，则不返回此字段。 code `string` 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。 message `string` 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。
usage `object` 输出信息统计。只对成功的结果计数。属性 video_duration `integer` 生成视频的时长，单位秒。枚举值为5。计费公式：费用 = 视频秒数 × 单价。 video_count `integer` 生成视频的数量。固定为1。 video_ratio `string` 当前仅当2.1模型返回该值。生成视频的比例，固定为standard。 SR `integer` 当前仅当2.2模型返回该值。生成视频的分辨率档位，枚举值为480、720、1080。
request_id `string` 请求唯一标识。可用于请求明细溯源和问题排查。

DashScope SDK调用

DK 的参数命名与HTTP接口基本一致，参数结构根据语言特性进行封装。

由于图生视频任务耗时较长（通常为1-5分钟），SDK 在底层封装了 HTTP 异步调用流程，支持同步、异步两种调用方式。

具体耗时受限于排队任务数和服务执行情况，请在获取结果时耐心等待。

Python SDK调用

Python SDK 支持两种图像输入方式：公网 URL、本地文件路径（绝对/相对），任选其一即可，具体参见输入图像。

说明

推荐安装最新版DashScope Python SDK，否则可能运行报错：安装或升级SDK。

同步调用

本示例展示同步调用方式，包括两种图像输入方式：公网URL、本地文件路径。

请求示例

import os
from http import HTTPStatus
# dashscope sdk >= 1.23.4
from dashscope import VideoSynthesis
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 从环境变量中获取 DashScope API Key（即阿里云百炼平台 API key）
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== 图像输入方式（二选一）==========
# 【方式一】使用公网图片 URL
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# 【方式二】使用本地文件路径（file://+文件路径）
# 使用绝对路径
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# 或使用相对路径
# first_frame_url = "file://" + "./first_frame.png"              # 以实际路径为准
# last_frame_url = "file://" + "./last_frame.png"                # 以实际路径为准

def sample_sync_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model="wan2.1-kf2v-plus",
                              prompt="写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
                              first_frame_url=first_frame_url,
                              last_frame_url=last_frame_url,
                              resolution="720P",
                              prompt_extend=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_sync_call_kf2v()

响应示例

video_url 有效期24小时，请及时下载视频。

{
    "status_code": 200,
    "request_id": "a37fafc3-907c-96f3-95a6-5b2a8268a3fd",
    "code": null,
    "message": "",
    "output": {
        "task_id": "4dba0092-da13-42b2-afb1-0f7b8a0f4643",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-05-23 15:50:12.404",
        "scheduled_time": "2025-05-23 15:50:12.443",
        "end_time": "2025-05-23 15:54:56.502",
        "orig_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
        "actual_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。它的黄色眼睛明亮有神，耳朵竖立，胡须清晰可见。背景是简洁的浅色墙面，突显它的黑色毛发和专注的表情。近景特写，强调它的眼神变化和姿态。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

异步调用

本示例展示异步调用方式。该方式会立即返回任务ID，需要自行轮询或等待任务完成。

请求示例

import os
from http import HTTPStatus
# dashscope sdk >= 1.23.4
from dashscope import VideoSynthesis
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 从环境变量中获取 DashScope API Key（即阿里云百炼平台 API key）
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== 图像输入方式（二选一）==========
# 【方式一】使用公网图片 URL
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# 【方式二】使用本地文件路径（file://+文件路径）
# 使用绝对路径
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# 或使用相对路径
# first_frame_url = "file://" + "./first_frame.png"              # 以实际路径为准
# last_frame_url = "file://" + "./last_frame.png"                # 以实际路径为准

def sample_async_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model="wan2.1-kf2v-plus",
                                    prompt="写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
                                    first_frame_url=first_frame_url,
                                    last_frame_url=last_frame_url,
                                    resolution="720P",
                                    prompt_extend=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # get the task information include the task status.
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)  # check the task status
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # wait the task complete, will call fetch interval, and check it's in finished status.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_async_call_kf2v()

响应示例

1、创建任务的响应示例

{
    "status_code": 200,
    "request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

2、查询任务结果的响应示例

video_url 有效期24小时，请及时下载视频。

{
    "status_code": 200,
    "request_id": "efa545b3-f95c-9e3a-a3b6-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-02-12 11:03:30.701",
        "scheduled_time": "2025-02-12 11:06:05.378",
        "end_time": "2025-02-12 11:12:18.853",
        "orig_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
        "actual_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。小猫毛发乌黑光亮，眼睛大而明亮，瞳孔呈金黄色。它抬头仰望，耳朵竖立，显得格外专注。镜头上移后，小猫转头直视镜头，眼神中充满好奇与警觉。背景简洁，突出它的细节特征。近景特写，自然光线柔和。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Java SDK调用

Java SDK 支持两种图像输入方式：公网 URL、本地文件路径（绝对路径），任选其一即可，具体参见输入图像。

说明

推荐安装最新版DashScope Java SDK，否则可能运行报错：安装或升级SDK。

同步调用

本示例展示同步调用方式，包括两种图像输入方式：公网URL、本地文件路径。

请求示例

// Copyright (c) Alibaba, Inc. and its affiliates.

// dashscope sdk >= 2.20.1
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.HashMap;
import java.util.Map;


public class Kf2vSyncIntl {

    static {
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    }

    // 从环境变量中获取 DashScope API Key（即阿里云百炼平台 API Key）
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * 图像输入方式（二选一）：
     *
     * 【方式一】公网URL
     */
    static String firstFrameUrl = "https://wanx.alicdn.com/material/20250318/first_frame.png";
    static String lastFrameUrl = "https://wanx.alicdn.com/material/20250318/last_frame.png";

     /**
     * 【方式二】本地文件路径（file://+绝对路径 or file:///+绝对路径）
     */
    // static String firstFrameUrl = "file://" + "/your/path/to/first_frame.png";  // Linux/macOS
    // static String lastFrameUrl = "file:///" + "C:/path/to/your/img.png";        // Windows

    public static void syncCall() {

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("resolution", "720P");

        VideoSynthesis videoSynthesis = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.1-kf2v-plus")
                        .prompt("写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("---sync call, please wait a moment----");
            result = videoSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        } catch (InputRequiredException e) {
            throw new RuntimeException(e);
        }
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        syncCall();
    }
}

响应示例

video_url 有效期24小时，请及时下载视频。

{
    "request_id": "e6bb4517-c073-9c10-b748-dedb8c11bb41",
    "output": {
        "task_id": "984784fe-83c1-4fc4-88c7-52c2c1fa92a2",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.mp4?xxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

异步调用

本示例展示异步调用方式。该方式会立即返回任务ID，需要自行轮询或等待任务完成。

请求示例

// Copyright (c) Alibaba, Inc. and its affiliates.

// dashscope sdk >= 2.20.1
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;

public class Kf2vAsync {

    static {
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    }
    
    // 从环境变量中获取 DashScope API Key（即阿里云百炼平台 API Key）
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * 图像输入方式（二选一）
     *
     * 【方式一】公网URL
     */
    static String firstFrameUrl = "https://wanx.alicdn.com/material/20250318/first_frame.png";
    static String lastFrameUrl = "https://wanx.alicdn.com/material/20250318/last_frame.png";

    /**
     * 【方式二】本地文件路径（file://+绝对路径 or file:///+绝对路径）
     */
    // static String firstFrameUrl = "file://" + "/your/path/to/first_frame.png";   // Linux/macOS
    // static String lastFrameUrl = "file:///" + "C:/path/to/your/img.png";        // Windows
    
    public static void asyncCall(){

        // 设置parameters参数
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("resolution", "720P");

        VideoSynthesis videoSynthesis = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.1-kf2v-plus")
                        .prompt("写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("---async call, please wait a moment----");
            result = videoSynthesis.asyncCall(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        } catch (InputRequiredException e) {
            throw new RuntimeException(e);
        }
        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();

        System.out.println("taskId=" + taskId);

        try {
            result = videoSynthesis.wait(taskId, apiKey);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        System.out.println(JsonUtils.toJson(result.getOutput()));
    }

    public static void main(String[] args){
        asyncCall();
    }
}

响应示例

1、创建任务的响应示例

{
    "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
    "output": {
        "task_id": "7277e20e-aa01-4709-xxxxxxxx",
        "task_status": "PENDING"
    }
}

2、查询任务结果的响应示例

video_url 有效期24小时，请及时下载视频。

{
    "request_id": "1625235c-c13e-93ec-aff7-xxxxxxxx",
    "output": {
        "task_id": "464a5e46-79a6-46fd-9823-xxxxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

使用限制

数据时效：任务task_id和视频url均只保留 24 小时，过期后将无法查询或下载。
音频支持：当前仅支持生成无声视频，不支持音频输出。如有需要，可通过语音合成生成音频。
内容审核：输入prompt 和图像、输出视频均会经过内容安全审核，含违规内容将返回 “IPInfringementSuspect”或“DataInspectionFailed”错误，详情请参见错误信息。

关键参数说明

输入图像

输入图像first_frame_url和last_frame_url参数均支持以下方式传入：

方式一：公网URL

一个公网可直接访问的地址，支持 HTTP/HTTPS。
示例值：https://example.com/images/cat.png。

方式二：本地文件路径（仅限 SDK）

Python SDK：支持传入文件的绝对路径和相对路径。文件路径规则如下：

系统	传入的文件路径	示例（绝对路径）	示例（相对路径）
Linux或macOS系统	file://{文件的绝对路径或相对路径}	file:///home/images/test.png	file://./images/test.png
Windows系统	file://{文件的绝对路径或相对路径}	file://D:/images/test.png	file://./images/test.png

Java SDK：仅支持传入文件的绝对路径。文件路径规则如下：
系统
传入的文件路径
示例（绝对路径）
Linux或macOS系统
file://{文件的绝对路径}
file:///home/images/test.png
Windows系统
file:///{文件的绝对路径}
file:///D:/images/test.png

计费和限流

模型免费额度和计费单价请参见模型列表与价格。
模型限流请参见通义万相系列。
计费说明：
- 按成功生成的 视频秒数 计费。仅当查询结果接口返回task_status为SUCCEEDED 并成功生成视频后，才会计费。
- 模型调用失败或处理错误不产生任何费用，也不消耗免费额度。

错误码

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

常见问题

视频FAQ快速入口：常见问题。

Q：如何生成特定宽高比（如3:4）的视频？

A：输出视频的宽高比由输入首帧图像（img_url）决定，但无法保证精确比例（如严格3:4）。

工作原理：模型以输入图像的宽高比为基准，然后根据 resolution 参数（如 480P / 720P / 1080P）将其适配到模型支持的合法分辨率。由于输出分辨率需满足技术要求（长和宽必须能被 16 整除），最终输出的宽高比可能存在微小偏差（例如从 0.75 调整为 0.739），属于正常现象。

示例：输入图像750×1000（宽高比 3:4 = 0.75），并设置 resolution = "720P"（目标总像素约 92 万），实际输出816×1104（宽高比 ≈ 0.739，总像素约90万）。
请注意，resolution 参数主要用于控制视频清晰度（总像素量），最终视频宽高比仍以输入图像为基础，仅做必要微调。

最佳实践：若需严格符合目标宽高比，请使用与目标比例一致的输入图像，并对输出视频进行后处理裁剪或填充。例如，使用视频编辑工具将输出视频裁剪至目标比例，或添加黑边、模糊背景进行填充适配。

响应参数	任务执行成功视频URL仅保留24小时，超时后会被自动清除，请及时保存生成的视频。 { "request_id": "ec016349-6b14-9ad6-8009-xxxxxx", "output": { "task_id": "3f21a745-9f4b-4588-b643-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-04-18 10:36:58.394", "scheduled_time": "2025-04-18 10:37:13.802", "end_time": "2025-04-18 10:45:23.004", "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxx", "orig_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。", "actual_prompt": "写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。它的黄色眼睛明亮有神，毛发光滑，胡须清晰可见。背景是简单的浅色墙面，突显它的黑色身影。近景特写，强调它的表情变化和眼神细节。" }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } 任务执行失败若任务执行失败，task_status将置为 FAILED，并提供错误码和信息。请参见错误信息进行解决。 `{ "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" } }` 任务查询过期 task_id查询有效期为 24 小时，超时后将无法查询，返回以下报错信息。 `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` 任务输出信息。属性 task_id `string` 任务ID。查询有效期24小时。 task_status `string` 任务状态。枚举值 PENDING：任务排队中 RUNNING：任务处理中 SUCCEEDED：任务执行成功 FAILED：任务执行失败 CANCELED：任务已取消 UNKNOWN：任务不存在或状态未知轮询过程中的状态流转： PENDING（排队中） → RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。初次查询状态通常为 PENDING（排队中）或 RUNNING（处理中）。当状态变为 SUCCEEDED 时，响应中将包含生成的视频url。若状态为 FAILED，请检查错误信息并重试。 submit_time `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_url `string` 视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时，可通过此URL下载视频。视频格式为MP4（H.264 编码）。 orig_prompt `string` 原始输入的prompt，对应请求参数`prompt`。 actual_prompt `string` 开启 prompt 智能改写后，返回实际使用的优化后 prompt。若未开启该功能，则不返回此字段。 code `string` 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。 message `string` 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。
usage `object` 输出信息统计。只对成功的结果计数。属性 video_duration `integer` 生成视频的时长，单位秒。枚举值为5。计费公式：费用 = 视频秒数 × 单价。 video_count `integer` 生成视频的数量。固定为1。 video_ratio `string` 当前仅当2.1模型返回该值。生成视频的比例，固定为standard。 SR `integer` 当前仅当2.2模型返回该值。生成视频的分辨率档位，枚举值为480、720、1080。
request_id `string` 请求唯一标识。可用于请求明细溯源和问题排查。

模型概览

前提条件

HTTP调用

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

请求参数

首尾帧生视频

使用反向提示词

请求头（Headers）

请求体（Request Body）

响应参数

成功响应

异常响应

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

请求参数

查询任务结果

请求头（Headers）

URL路径参数（Path parameters）

响应参数

任务执行成功

任务执行失败

任务查询过期

DashScope SDK调用

Python SDK调用

同步调用

请求示例

响应示例

异步调用

请求示例

响应示例

Java SDK调用

同步调用

请求示例

响应示例

异步调用

请求示例

响应示例

使用限制

关键参数说明

输入图像

方式一：公网URL

方式二：本地文件路径（仅限 SDK）

计费和限流

错误码

常见问题

Q：如何生成特定宽高比（如3:4）的视频？