The Wan 2.2 model generates a smoothly transitioning video from a first frame, a last frame, and a text prompt.
Related documents: User guide
Usage notes
To ensure successful API calls, your model, endpoint URL, and API key must be in the same region. Cross-region calls will fail.
-
Select a model: Confirm the region where the model is available.
-
Select a URL: Choose the endpoint URL that corresponds to your region. Both HTTP URLs and DashScope SDK URLs are supported.
-
Configure your API key: Select a region, get your API key, and then set it as an environment variable.
-
Install the SDK: To make API calls using the SDK, install the DashScope SDK.
The code examples in this topic apply to Singapore.
Model Studio has released a workspace-specific domain for the Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope-intl.aliyuncs.com to the new domain.
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Model Studio console. The existing domain remains fully functional.
HTTP call
Because image-to-video tasks are long-running operations that typically take 1 to 5 minutes, the API uses an asynchronous call. The process involves two core steps: create a task, then poll for the result.
Step 1: Create a task
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
Replace WorkspaceId with your actual Workspace ID.
China (Beijing)
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
-
After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result. -
For guidance for beginners, see Call APIs with Postman or cURL.
Request parameters |
First and last framesGenerates a video based on a first frame, a last frame, and a prompt. Negative promptUse the negative_prompt parameter to exclude certain elements, such as people, from the generated video. |
Request headers |
|
|
Content-Type The content type of the request. Must be |
|
|
Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. |
|
|
X-DashScope-Async Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be Important
If this request header is missing, the error "current user api does not support synchronous calls" is returned. |
|
Request body |
|
|
model The name of the model. Example: wan2.2-kf2v-flash. For details, see the Model Studio console. |
|
|
input Contains the primary input for the task, such as the prompt. |
|
|
parameters Video processing parameters. |
Response parameters |
Successful responseSave the Error responseTask creation failed. See Error codes. |
|
output The output information for the task. |
|
|
request_id Unique request identifier for tracing and troubleshooting. |
|
|
code Error code. Returned only for failed requests. See Error codes. |
|
|
message Detailed error message. Returned only for failed requests. See Error codes. |
Step 2: Query the result
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Replace WorkspaceId with your actual Workspace ID.
China (Beijing)
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
-
Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
-
Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
-
Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
-
task_idvalidity: 24 hours. After this period, queries return the task status asUNKNOWN.
Request parameters |
Query task resultReplace API keys are different for each region. For more information, see Obtain an API key. If you use a model in the China (Beijing) region, replace |
Request headers |
|
|
Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. |
|
Path parameters |
|
|
task_id The ID of the task. |
Response parameters |
Task succeededVideo URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. Task failedWhen a task fails, Task query expiredThe |
|
output The output information for the task. |
|
|
usage Task usage statistics. Only successful tasks are billed. |
|
|
request_id Unique request identifier for tracing and troubleshooting. |
DashScope SDK calls
The SDK's parameter names are largely consistent with the HTTP API, and the parameter structure follows the conventions of each programming language.
Because image-to-video tasks are long-running (typically 1–5 minutes), the SDK handles the asynchronous HTTP calls internally, supporting both synchronous and asynchronous call methods.
The actual processing time depends on the number of tasks in the queue and service performance. Please be patient.
Python SDK calls
Before you run the following code, ensure your DashScope Python SDK version is at least 1.23.8.
Older versions may trigger errors such as "url error, please check url!". See Install SDK to update.
Set the base_http_api_url based on the model's region:
Singapore
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
Replace WorkspaceId with your actual Workspace ID.
Beijing
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
Sample code
Synchronous call
This example demonstrates a synchronous call with two image input methods: a public URL and a 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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Get the DashScope API key (which is your Model Studio API key) from an 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. Please download the video within this period.{
"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, and its whiskers are clearly visible. The background is a simple, light-colored wall that 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 demonstrates an asynchronous call, which immediately returns a task ID. You must then poll for the task status or wait for the task to complete.
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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Get the DashScope API key (which is your Model Studio API key) from an 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, including 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 for the task to complete. This method polls the fetch endpoint at intervals until the task is finished.
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 upon task creation
{
"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. Example response for a completed task
The video_url is valid for 24 hours. Please download the video within this period.{
"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 glossy, 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 face the camera, its eyes filled with 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 calls
Before you run the following code, ensure your DashScope Java SDK version is at least 2.20.9.
Older versions may trigger errors such as "url error, please check url!". See Install SDK to update.
Sample code
Synchronous call
This example demonstrates 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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// Get the DashScope API key (which is your Model Studio API key) from an 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 {
// Making a synchronous call. This may take 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. Please download the video within this period.{
"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 demonstrates an asynchronous call, which immediately returns a task ID. You must then poll for the task status or wait for the task to complete.
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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// Get the DashScope API key (which is your Model Studio API key) from an 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 {
// Making an asynchronous call.
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 upon task creation
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}2. Example response for a completed task
The video_url is valid for 24 hours. Please download the video within this period.{
"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
task_idand videovideo_urlare retained for 24 hours, after which they cannot be queried or downloaded. -
Audio support: The service generates silent videos only. To generate audio, use speech synthesis.
-
Content Moderation: Content Moderation reviews all input prompts, images, and output videos. If any content violates the usage policies, the service returns an "IPInfringementSuspect" or "DataInspectionFailed" error. For details, see Error codes.
Error codes
If a model call fails, see Error codes for troubleshooting.
FAQ
Q: How to generate a specific aspect ratio?
A: The output video's aspect ratio depends on the first frame image (first_frame_url). However, an exact ratio (such as a strict 3:4) cannot be guaranteed, and may deviate slightly.
-
Why does the aspect ratio deviate?
The model uses the input image's aspect ratio as a baseline and calculates the closest valid resolution based on the total pixels of the selected
resolutionsetting. Because the video's width and height must be multiples of 16, the model makes minor adjustments to the final resolution.-
For example, if you provide a 750×1000 input image (an aspect ratio of 3:4 or 0.75) and set
resolutionto "720P" (targeting approximately 920,000 pixels), the actual output might be 816×1104 (an aspect ratio of approximately 0.739, with about 900,000 pixels).
-
-
Recommendations:
-
Input Image: For best results, use a first frame image that matches your target aspect ratio.
-
Post-processing: If a strict aspect ratio is required, use a video editing tool to crop the generated video or add black bars.
-
Q: How do I get the domain name whitelist for video storage?
A: Videos generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.