Wan Image-to-Video API Reference - Alibaba Cloud Model Studio

The Wan kf2v model generates a smoothly transitioning video from a first frame image, a last frame image, and a text prompt.

References: User guide

Availability

To ensure successful API calls, the model, endpoint URL, and API key must belong to the same region. Cross-region calls will fail.

Select a model: Confirm the model is available in your target region.
Select a URL: Choose the endpoint URL for your region. Both HTTP URLs and DashScope SDK URLs are supported.
Configure your API key: Select your region and get your API key. Then configure your API key as an environment variable.
Install the SDK: If you plan to call the API using the SDK, install the DashScope SDK.

Note

Sample codes in this topic apply to the Singapore region.

HTTP

Because image-to-video tasks typically take 1 to 5 minutes, the API uses asynchronous calls. The full process has two core steps: Create a task → Poll for the result.

Step 1: Create a task

Singapore

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

Beijing

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

Note

After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
For a beginner's tutorial, see Postman.

Request parameters	Image-to-video from first and last frames Generate a video based on the first frame, last frame, and a 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.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": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view." }, "parameters": { "resolution": "480P", "prompt_extend": true } }' Use a negative prompt Use the negative_prompt parameter to prevent the generated video from containing "people". 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": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.", "negative_prompt": "people" }, "parameters": { "resolution": "720P", "prompt_extend": true } }'
Request headers
Content-Type `string` (Required) The content type of the request. Must be `application/json`.
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
X-DashScope-Async `string` (Required) Enables asynchronous processing. Must be `enable` as HTTP requests support only asynchronous processing. Important Returns "current user api does not support synchronous calls" error if not included.
Request body
model `string` (Required) The model name. Example: wan2.2-kf2v-flash. For more information, see Model list and pricing.
input `object` (Required) Basic input information, including the prompt. Properties prompt `string` (Optional) The text prompt. Supports Chinese and English. Maximum length: 800 characters. Each Chinese character or letter counts as one character. Text exceeding the limit is automatically truncated. If the subject or scene changes significantly between the first and last frames, describe the transition—for example, camera movement (camera moves left) or subject movement (person runs forward). Example: A small black cat looks up at the sky curiously. The camera gradually rises from eye level and finally captures its curious gaze from a top-down view. For prompt best practices, see Prompt guide for text-to-video and image-to-video. negative_prompt `string` (Optional) A negative prompt that describes content you do not want in the video. This helps constrain output. Supports Chinese and English. Maximum length: 500 characters. Text exceeding the limit is automatically truncated. Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions. first_frame_url `string` (Required) The URL of the first frame image. The aspect ratio of the output video matches this image. The URL must be publicly accessible and support HTTP or HTTPS. Image requirements: Format: JPEG, JPG, PNG (alpha channels not supported), BMP, or WEBP. Resolution: Width and height must be between 360 and 2000 pixels. File size: No more than 10 MB. last_frame_url `string` (Required) The URL of the last frame image. The URL must be publicly accessible and support HTTP or HTTPS. Image requirements: Format: JPEG, JPG, PNG (alpha channels not supported), BMP, or WEBP. Resolution: Width and height must be between 360 and 2000 pixels. The resolution may differ from the first frame image. Alignment is not required. File size: No more than 10 MB.
parameters `object` (Optional) Video processing parameters. Properties resolution `string` (Optional) Important The resolution affects cost directly. For the same model: 1080P > 720P > 480P. Confirm the model pricing before calling. The resolution tier for the generated video. This adjusts only the definition (total pixels) and does not change the aspect ratio. The video's aspect ratio matches the first frame image specified by first_frame_url. The default value and available values depend on the model parameter: wan2.2-kf2v-flash: Options are 480P, 720P, and 1080P. Default is `720P`. wan2.1-kf2v-plus: Option is 720P. Default is `720P`. Example: 720P. duration `integer` (Optional) Important The duration affects cost directly. Billing is per second. Confirm the model pricing before calling. The duration of the generated video in seconds. This value is fixed at 5 and cannot be changed. The model always generates a 5-second video. prompt_extend `bool` (Optional) Enable prompt rewriting. If enabled, a large language model rewrites the input prompt. This improves results for short prompts but increases processing time. true (default) false Example: true. watermark `bool` (Optional) Adds a watermark to the bottom-right corner of the image displaying "AI-generated". false (default) true Example: false. seed `integer` (Optional) The random number seed. Must be an integer between `0` and `2147483647`. If not provided, a random seed is generated. Using a fixed seed improves reproducibility, though results may still vary due to model randomness. Example: `12345`

Response parameters	Successful response Save the `task_id` to query the task status and result. `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` Error response Task creation failed. See error codes to resolve the issue. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` The task output information. Properties task_id `string` The ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.
code `string` The error code. Returned only when the request fails. See error codes for details.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.

Step 2: Query task result

Singapore

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Beijing

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Note

Polling suggestion: Video generation can take several minutes. We recommend that you use a polling mechanism with a reasonable query interval, such as 15 seconds, to retrieve the result.
Task status transition: PENDING → RUNNING → SUCCEEDED or FAILED.
Result URL: After the task is successful, a video URL is returned. The URL is valid for 24 hours. After you retrieve the URL, you must immediately download and save the video to a permanent storage service, such as Object Storage Service (OSS).
task_id validity: 24 hours. After this period, you cannot query the result, and the API returns a task status of UNKNOWN.

Request parameters	Query task result Replace `86ecf553-d340-4e21-xxxxxxxxx` with the actual task ID. API keys are region-specific. See API key documentation for details. For models in the Beijing region, replace base_url with `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"`
Request headers
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
Path parameters
task_id `string` (Required) The ID of the task to query.

Response parameters	Task succeeded Video URLs are retained for only 24 hours and then automatically purged. Save generated videos promptly. { "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": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.", "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's yellow eyes are bright and expressive, its fur is smooth, and its whiskers are clearly visible. The background is a simple light-colored wall, highlighting the cat's black silhouette. A close-up shot emphasizes the changes in the cat's expression and the details of its eyes." }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } Task failed When a task fails, `task_status` is set to FAILED with an error code and message. See error codes to resolve the issue. `{ "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 query expired The `task_id` is valid for 24 hours. After this period, queries fail and return the following error message. `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` The task output information. Properties task_id `string` The ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown Status transitions during polling: PENDING → RUNNING → SUCCEEDED or FAILED First query typically returns PENDING or RUNNING SUCCEEDED status includes the generated video URL in the response FAILED status requires checking the error message and retrying submit_time `string` The time when the task was submitted. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. scheduled_time `string` The time when the task started running. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. end_time `string` The time when the task was completed. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. video_url `string` The URL of the generated video. Returned only when `task_status` is SUCCEEDED. URL is valid for 24 hours. Use to download the video in MP4 format with H.264 encoding. orig_prompt `string` The original input prompt. This is the value of the `prompt` request parameter. actual_prompt `string` Returns the actual optimized prompt used when prompt rewriting is enabled. Not returned when this feature is disabled. code `string` The error code. Returned only when the request fails. See error codes for details. message `string` Detailed error message. Returned only when the request fails. See error codes for details.
usage `object` Usage statistics. Counts only successful results. Properties video_duration `integer` The video duration in seconds. Value: 5. Billing formula: Cost = Video duration (seconds) × Unit price. video_count `integer` The number of videos generated. Fixed at 1. video_ratio `string` Returned only by the 2.1 model. The video aspect ratio. Fixed at standard. SR `integer` Returned only by the 2.2 model. The video resolution tier. Values: 480, 720, or 1080.
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.

DashScope SDK

SDK parameter names match those in the HTTP API. Parameter structures are encapsulated according to language-specific conventions.

Because image-to-video tasks typically take 1 to 5 minutes, the SDK wraps the HTTP async call logic and supports both synchronous and asynchronous calls.

The actual time depends on queue length and service performance. Please wait patiently for the result.

Python SDK

Important

Ensure your DashScope Python SDK version is at least 1.23.8 before running the code below. An older version may trigger errors like "url error, please check url!". Update using the SDK installation guide.

Set base_http_api_url based on your model's region:

Singapore

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

Beijing

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

Sample code

Synchronous call

This example shows a synchronous call with two image input methods: public URL and local file path.

Request example

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'

# Get the DashScope API key (Model Studio API key) from the environment variable
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== Image input method (choose one) ==========
# [Method 1] Use a public image 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"

# [Method 2] Use a local file path (file:// + file path)
# Use an absolute path
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# Or use a relative path
# first_frame_url = "file://" + "./first_frame.png"              # Use your actual path
# last_frame_url = "file://" + "./last_frame.png"                # Use your actual path

def sample_sync_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model="wan2.2-kf2v-flash",
                              prompt="Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
                              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()

Response example

The video_url is valid for 24 hours. Download the video promptly.

{
    "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": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's yellow eyes are bright and expressive, its ears are pricked up, and its whiskers are clearly visible. The background is a simple, light-colored wall, which highlights the cat's black fur and focused expression. A close-up shot emphasizes the change in the cat's gaze and posture."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Asynchronous call

This example shows an asynchronous call. It returns a task ID immediately. You must then poll for the result or wait for completion.

Request example

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'

# Get the DashScope API key (Model Studio API key) from the environment variable
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== Image input method (choose one) ==========
# [Method 1] Use a public image 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"

# [Method 2] Use a local file path (file:// + file path)
# Use an absolute path
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# Or use a relative path
# first_frame_url = "file://" + "./first_frame.png"              # Use your actual path
# last_frame_url = "file://" + "./last_frame.png"                # Use your actual path

def sample_async_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model="wan2.2-kf2v-flash",
                                    prompt="Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
                                    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()

Response example

1. Response for creating a task

{
    "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. Response for querying a task result

The video_url is valid for 24 hours. Download the video promptly.

{
    "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": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's fur is jet black and shiny, its eyes are large and bright with golden pupils. It looks up with its ears pricked, appearing exceptionally focused. After the camera moves up, the cat turns to look directly at the camera, its eyes full of curiosity and alertness. The background is simple, highlighting the cat's detailed features. A close-up shot with soft, natural light."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Java SDK

Important

Ensure your DashScope Java SDK version is at least 2.20.9 before running the code below. An older version may trigger errors like "url error, please check url!". Update using the SDK installation guide.

Sample code

Synchronous call

This example shows a synchronous call with two image input methods: public URL and local file path.

Request example

// 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";
    }

    // Get the DashScope API key (Model Studio API key) from the environment variable
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input method (choose one):
     *
     * [Method 1] Public 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";

     /**
     * [Method 2] Local file path (file:// + absolute path or file:/// + absolute path)
     */
    // 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("Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.")
                        .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();
    }
}

Response example

The video_url is valid for 24 hours. Download the video promptly.

{
    "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"
    }
}

Asynchronous call

This example shows an asynchronous call. It returns a task ID immediately. You must then poll for the result or wait for completion.

Request example

// 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";
    }
    
    // Get the DashScope API key (Model Studio API key) from the environment variable
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input method (choose one)
     *
     * [Method 1] Public 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";

    /**
     * [Method 2] Local file path (file:// + absolute path or file:/// + absolute path)
     */
    // 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(){

        // Set 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.2-kf2v-flash")
                        .prompt("Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.")
                        .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();
    }
}

Response example

1. Response for creating a task

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

2. Response for querying a task result

The video_url is valid for 24 hours. Download the video promptly.

{
    "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"
    }
}

Limitations

Data retention: The task_id and video_url are retained for 24 hours. After expiration, they cannot be queried or downloaded.
Audio support: This service generates silent videos only. Audio output is not supported. To generate audio, use the speech synthesis service.
Content moderation: Content Moderation reviews all input prompts, images, and output videos. If content violates our policies, the system returns an "IPInfringementSuspect" or "DataInspectionFailed" error. For details, see Error messages.

Error codes

If a model call fails and returns an error message, see Error messages for troubleshooting.

FAQ

Q: How do I generate a video with a specific aspect ratio, such as 3:4?

A: The output video's aspect ratio is determined by the first frame image (first_frame_url). However, exact ratios (e.g., strict 3:4) are not guaranteed and may vary slightly.

Why does drift occur: The model uses the aspect ratio of your input image as a baseline and automatically calculates the closest valid resolution based on the total number of pixels specified in the resolution setting. Because video dimensions must be multiples of 16, the model fine-tunes the final resolution. As a result, the output aspect ratio may not be exactly 3:4, but it will be very close.

For example: input image 750×1000 (aspect ratio 3:4 = 0.75), and set resolution = "720P" (target total pixels about 920,000), actual output 816×1104 (aspect ratio ≈ 0.739, total pixels about 900,000).

Best practices:

Input control: Use a first-frame image with an aspect ratio as close as possible to your target.
Post-processing: If you require exact ratios, crop or add black bars to the generated video using editing tools.

Availability

HTTP

Step 1: Create a task

Singapore

Beijing

Request parameters

Image-to-video from first and last frames

Use a negative prompt

Request headers

Request body

Response parameters

Successful response

Error response

Step 2: Query task result

Singapore

Beijing

Request parameters

Query task result

Request headers

Path parameters

Response parameters

Task succeeded

Task failed

Task query expired

DashScope SDK

Python SDK

Singapore

Beijing

Sample code

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Java SDK

Sample code

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Limitations

Error codes

FAQ

Q: How do I generate a video with a specific aspect ratio, such as 3:4?