Skip to main content
万相-早期视频模型(2.1-2.6)

万相-首尾帧生视频API参考(2.2)

万相2.2-首尾帧生视频模型基于 首帧图像 、 尾帧图像和文本提示词 ,生成一段平滑过渡的视频。

相关文档使用指南

适用范围

为确保调用成功,请务必保证模型、Endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
本文的示例代码适用于新加坡地域
阿里云百炼为华北2(北京)、新加坡地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议迁移至新域名:
  • 华北2(北京)地域:从 https://dashscope.aliyuncs.com 迁移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域:从 https://dashscope-intl.aliyuncs.com 迁移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。

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/jsonAuthorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable
缺少此请求头将报错:“current user api does not support synchronous calls”。
请求体(Request Body)
model string (必选)模型名称。示例值:wan2.2-kf2v-flash。详情参见百炼控制台。input object (必选)输入的基本信息,如提示词等。

属性

prompt string (可选)文本提示词。支持中英文,长度不超过800个字符,每个汉字/字母占一个字符,超过部分会自动截断。如果首尾帧的主体和场景变化较大,建议描写变化过程,例如运镜过程(镜头向左移动)或者主体运动过程(人向前奔跑)。示例值:一只黑色小猫好奇地看向天空,镜头从平视逐渐上升,最后俯拍它的好奇的眼神。提示词的使用技巧请参见文生视频/图生视频Prompt指南negative_prompt string (可选)反向提示词,用来描述不希望在视频画面中看到的内容,可以对视频画面进行限制。支持中英文,长度不超过500个字符,超过部分会自动截断。示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。first_frame_url string (必选)首帧图像URL。输出视频的宽高比与首帧图像保持一致。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。图像限制:
  • 图像格式:JPEG、JPG、PNG(不支持透明通道)、BMP、WEBP。
  • 图像分辨率:图像的宽度和高度范围为[240,8000],单位为像素。
  • 文件大小:不超过10MB。
last_frame_url string (必选)尾帧图像URL。URL 需为公网可访问地址,支持 HTTP 或 HTTPS 协议。图像限制:
  • 图像格式:JPEG、JPG、PNG(不支持透明通道)、BMP、WEBP。
  • 图像分辨率:图像的宽度和高度范围为[240,8000],单位为像素。尾帧图像分辨率可与首帧不同,无需强制对齐。
  • 文件大小:不超过10MB。
parameters object (可选)视频处理参数。

属性

resolution string (可选)
resolution直接影响费用,同一模型:1080P > 720P > 480P,调用前请确认百炼控制台。
生成的视频分辨率档位。仅用于调整视频的清晰度(总像素),不改变视频的宽高比,视频宽高比将与首帧图像 first_frame_url 的宽高比保持一致此参数的默认值和可用枚举值依赖于 model 参数,规则如下:
  • wan2.2-kf2v-flash:可选值:480P、720P、1080P。默认值为720P
  • wan2.1-kf2v-plus:可选值:720P。默认值为720P
示例值:720P。duration integer (可选)
duration直接影响费用,按秒计费,调用前请确认百炼控制台。
视频生成时长,单位为秒。当前参数值固定为5,且不支持修改。模型将始终生成5秒时长的视频。prompt_extendbool (可选)是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。
  • true:默认值,开启智能改写。
  • false:不开启智能改写。
示例值:true。watermark bool (可选)是否添加水印标识,水印位于图片右下角,文案为“AI生成”。
  • false:默认值,不添加水印。
  • true:添加水印。
示例值:false。seedinteger(可选)随机数种子,取值范围为[0, 2147483647]未指定时,系统自动生成随机种子。若需提升生成结果的可复现性,建议固定seed值。请注意,由于模型生成具有概率性,即使使用相同 seed,也不能保证每次生成结果完全一致。
  • 首尾帧生视频
  • 使用反向提示词
根据首帧、尾帧和prompt生成视频。
# 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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.2-kf2v-flash",
    "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
    }
}'

响应参数

output object任务输出信息。

属性

task_id string任务ID。查询有效期24小时。task_status string任务状态。

枚举值

  • PENDING:任务排队中
  • RUNNING:任务处理中
  • SUCCEEDED:任务执行成功
  • FAILED:任务执行失败
  • CANCELED:任务已取消
  • UNKNOWN:任务不存在或状态未知
request_idstring请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码
  • 成功响应
  • 异常响应
请保存 task_id,用于查询任务状态与结果。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

步骤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_id string(必选)任务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。
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

响应参数

outputobject任务输出信息。

属性

task_id string任务ID。查询有效期24小时。task_status string任务状态。

枚举值

  • PENDING:任务排队中
  • RUNNING:任务处理中
  • SUCCEEDED:任务执行成功
  • FAILED:任务执行失败
  • CANCELED:任务已取消
  • UNKNOWN:任务不存在或状态未知
轮询过程中的状态流转:
  • PENDING(排队中) → RUNNING(处理中)→ SUCCEEDED(成功)/ FAILED(失败)。
  • 初次查询状态通常为 PENDING(排队中)或 RUNNING(处理中)。
  • 当状态变为 SUCCEEDED 时,响应中将包含生成的视频URL。
  • 若状态为 FAILED,请检查错误信息并重试。
  • 若状态为 CANCELED,表示任务已取消,如需继续请重新提交任务。
  • 若状态为 UNKNOWN,表示任务不存在或状态未知,可能在 task_id 不存在或超过 24 小时有效期后出现。
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_urlstring视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时,可通过此URL下载视频。视频格式为MP4(H.264 编码)。orig_prompt string原始输入的prompt,对应请求参数promptactual_prompt string开启 prompt 智能改写后,返回实际使用的优化后 prompt。若未开启该功能,则不返回此字段。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码
usage object输出信息统计。只对成功的结果计数。

属性

video_duration integer生成视频的时长,单位秒。枚举值为5。计费公式:费用 = 视频秒数 × 单价。video_count integer生成视频的数量。固定为1。video_ratio string当前仅当2.1模型返回该值。生成视频的比例,固定为standard。SR integer当前仅当2.2模型返回该值。生成视频的分辨率档位,枚举值为480、720、1080。
request_idstring请求唯一标识。可用于请求明细溯源和问题排查。
  • 任务执行成功
  • 任务执行失败
  • 任务查询过期
视频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
    }
}

DashScope SDK调用

SDK 的参数命名与HTTP接口基本一致,参数结构根据语言特性进行封装。 由于图生视频任务耗时较长(通常为1-5分钟),SDK 在底层封装了 HTTP 异步调用流程,支持同步、异步两种调用方式。
具体耗时受限于排队任务数和服务执行情况,请在获取结果时耐心等待。

Python SDK调用

请确保 DashScope Python SDK 版本不低于1.23.8,再运行以下代码。若版本过低,可能会触发 “url error, please check url!” 等错误。请参考安装SDK进行更新。
根据模型所在地域设置 base_http_api_url:
  • 新加坡
  • 北京
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'调用时请将{WorkspaceId}替换为真实的业务空间ID

示例代码

  • 同步调用
  • 异步调用
本示例展示同步调用方式,包括两种图像输入方式:公网URL、本地文件路径。
请求示例
import os
from http import HTTPStatus
# dashscope sdk >= 1.23.4
from dashscope import VideoSynthesis
import dashscope

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.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.2-kf2v-flash",
                              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"
    }
}

Java SDK调用

请确保 DashScope Java SDK 版本不低于2.20.9,再运行以下代码。若版本过低,可能会触发 “url error, please check url!” 等错误。请参考安装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://{WorkspaceId}.ap-southeast-1.maas.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.2-kf2v-flash")
                        .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"
    }
}

使用限制

  • 数据时效:任务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万)。
  • 实践建议
    • 输入控制:尽量使用与目标比例一致的图片作为首帧输入。
    • 后期处理:如果您对比例有严格要求,建议在视频生成后,使用编辑工具进行简单的裁剪或黑边填充。

Q:如何获取视频存储的访问域名白名单?

A: 模型生成的视频存储于阿里云OSS,API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置,请注意:由于底层存储会根据业务情况进行动态变更,为避免过期信息影响访问,文档不提供固定的OSS域名白名单。如有安全管控需求,请联系客户经理获取最新OSS域名列表。
文本生成
图像生成
音频
Realtime API
  • 概述
向量与排序
模型生产