This topic describes the input and output parameters of the Wan Image-to-video model.
Model overview
Wan Image-to-video transforms static images into dynamic videos. It features strong instruction-following capabilities, supports complex movements and realistic physics, and generates videos with rich artistic styles and cinematic visual quality.
You can experience it on the Wan official website.
The features on the official website may differ from the capabilities supported by the API. For specific capabilities, refer to those listed in this topic. This topic will be updated promptly when new features are added.
Performance showcase
Sample input | Output video |
Prompt: A cat running on the grass Image: | Output video: Takes the input image as the first frame, then generates the subsequent video content based on a prompt. Model: wan2.1-i2v-turbo. |
Model introduction
Name | Description |
wan2.1-i2v-turbo | Faster generation, taking only one-third of the time of the Plus model, offering better cost-effectiveness. |
wan2.1-i2v-plus | Rich details and enhanced texture. |
Name | Unit price | Rate limits (shared between Alibaba Cloud account and RAM users) | Free quota | |
Requests per second (RPS) for task submission | Number of concurrent tasks | |||
wan2.1-i2v-turbo | $0.036/second | 2 | 2 | Free quota: 200 seconds each Valid for 180 days after activation |
wan2.1-i2v-plus | $0.10/second | 2 | 2 |
Learn more about Billing and rate limiting.
Prerequisites
The image-to-video API supports calls through HTTP and DashScope SDK.
Before you make a call, you must first obtain an API key and set the API key as an environment variable.
If you need to use SDK, you must install the SDK for Python or Java.
HTTP
The video generation model processing takes a relatively long time. To avoid request timeouts, HTTP calls only support asynchronous retrieval of model results. You need to make two requests:
Create task: Send a request to create a task, which will return a task ID.
Query results using the ID: Use the task ID to query the task status and results. If successful, a video URL will be returned, which is valid for 24 hours.
After you create a task, it will be added to a queue. Later, call the query interface to get the task status and results based on the task ID.
Image-to-video generation takes a relatively long time. The turbo model takes 3-5 minutes, while the plus model takes 7-10 minutes. The actual time depends on the number of queued tasks and network conditions.
Step 1: Create task
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Request parameters | Image-to-video
|
Headers | |
Content-Type The type of the request content. This parameter must be set to | |
Authorization The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a. | |
X-DashScope-Async The asynchronous processing parameter. HTTP requests only support asynchronous mode, so this parameter must be set to | |
Request body | |
model The model name. Example value: wan2.1-i2v-turbo. | |
input Basic input information, such as prompts. | |
parameters The video processing parameters. |
Response parameters | Successful response
Error response
|
output The task output information. | |
request_id The request ID. It can be used for tracing and troubleshooting. | |
code The error code for a failed request. This parameter is not returned when the request is successful. | |
message The error message for a failed request. This parameter is not returned when the request is successful. |
Step 2: Query results by task ID
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
Request parameters | Query task resultsReplace
|
Headers | |
Authorization The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a. | |
Path parameters | |
task_id The task ID. |
Response parameters | Task succeededTask data (such as task status and video URL) will be automatically deleted after 24 hours. Save the generated videos promptly.
Task failedIf the task fails for some reason, the task status will be set to FAILED, and the code and message fields will show the reason.
|
output The task output information. | |
usage The output statistics. It only counts successful results. | |
request_id The request ID. It can be used for tracing and troubleshooting. |
Dashscope SDK
Make sure you have installed the latest version of the DashScope SDK. Otherwise, you might encounter errors.
DashScope SDK currently supports Python and Java.
The parameter names in the SDK are basically the same as the HTTP interface. The parameter structure depends on the SDK encapsulation of different languages. For parameter descriptions, refer to HTTP.
Because video model processing takes a long time, the underlying service uses an asynchronous approach. The SDK provides encapsulation at the upper layer and supports both synchronous and asynchronous calling methods.
Image-to-video generation takes a relatively long time. The turbo model takes 3-5 minutes, while the plus model takes 7-10 minutes. The actual time depends on the number of queued tasks and network conditions.
Python SDK
When processing image files using the Python SDK, you can provide either a public URL or a local file path. Choose one of the following two methods.
Public URL: The URL must be publicly accessible and support HTTP or HTTPS protocol.
Local file path: You can provide either the absolute path or the relative path of the file, see the following table:
Operating system | File path format | Example (absolute) | Example (relative) |
Linux or macOS | file://{absolute or relative path of the file} | file:///home/images/test.png | file://./images/test.png |
Windows | file://D:/images/test.png | file://./images/test.png |
Synchronous calling
Sample request
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 DashScope API Key from environment variables (Alibaba Cloud Model Studio API key)
api_key = os.getenv("DASHSCOPE_API_KEY")
# ========== Image input methods (choose one) ==========
# [Method 1] Use a public image URL
img_url = "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
# [Method 2] Use a local file path (file://+file path)
# Using absolute path
# img_url = "file://" + "/path/to/your/img.png" # Linux/macOS
# img_url = "file://" + "C:/path/to/your/img.png" # Windows
# Or using relative path
# img_url = "file://" + "./img.png" # Use actual path
def sample_async_call_i2v():
# call async api, will return the task information
# you can get task status with the returned task id.
rsp = VideoSynthesis.async_call(model='wan2.1-i2v-turbo',
prompt='a cat running on the grass',
img_url=img_url)
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(rsp)
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(rsp)
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_i2v()
Sample response
The video_url is valid for 24 hours. Download the video promptly.
{
"status_code": 200,
"request_id": "aead6248-1bb3-9506-8c72-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "3bd8b12f-da4d-4882-badb-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx",
"submit_time": "2025-02-12 10:35:47.260",
"scheduled_time": "2025-02-12 10:35:48.304",
"end_time": "2025-02-12 10:41:13.449",
"orig_prompt": "a cat running on the grass",
"actual_prompt": "a cat running on the grass, stable camera movement, stable image, high definition, close-up, exquisite, professional video"
},
"usage": {
"video_count": 1,
"video_duration": 5,
"video_ratio": "standard"
}
}
Asynchronous calling
Sample request
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 DashScope API Key from environment variables (Alibaba Cloud Model Studio API key)
api_key = os.getenv("DASHSCOPE_API_KEY")
# ========== Image input methods (choose one) ==========
# [Method 1] Use a public image URL
img_url = "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
# [Method 2] Use a local file path (file://+file path)
# Using absolute path
# img_url = "file://" + "/path/to/your/img.png" # Linux/macOS
# img_url = "file://" + "C:/path/to/your/img.png" # Windows
# Or using relative path
# img_url = "file://" + "./img.png" # Use actual path
def sample_async_call_i2v():
# call async api, will return the task information
# you can get task status with the returned task id.
rsp = VideoSynthesis.async_call(api_key=api_key,
model='wan2.1-i2v-turbo',
prompt='a cat running on the grass',
img_url=img_url)
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(rsp)
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(rsp)
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_i2v()
Sample response
1. Create task
{
"status_code": 200,
"request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
"code": "",
"message": "",
"output": {
"task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
"task_status": "PENDING",
"video_url": ""
},
"usage": null
}
2. Query task results
The video_url is valid for 24 hours. Download the video promptly.
{
"status_code": 200,
"request_id": "c62edc62-5b7a-9d21-9d55-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx",
"submit_time": "2025-02-12 10:25:57.668",
"scheduled_time": "2025-02-12 10:28:04.052",
"end_time": "2025-02-12 10:32:43.580"
},
"usage": {
"video_count": 1,
"video_duration": 5,
"video_ratio": "standard"
}
}
Java SDK
When processing image files using the Java SDK, you can provide either a public URL or a local file path. Choose one of the following two methods.
Public file URL: The URL must be publicly accessible and support HTTP or HTTPS protocol.
Local file path: Only absolute paths are supported, see the following table.
Operating system | File path format | Example |
Linux or macOS | file://{absolute path of the file} | file:///home/images/test.png |
Windows | file:///{absolute path of the file} | file:///D:/images/test.png |
Synchronous calling
Sample request
// 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 Image2Video {
static {
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// Get DashScope API Key from environment variables (Alibaba Cloud Model Studio API key)
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Image input methods (choose one)
*
* [Method 1] Public URL
*/
static String imgUrl = "https://cdn.translate.alibaba.com/r/wanx-demo-1.png";
/**
* [Method 2] Local file path (file://+absolute path or file:///+absolute path)
*/
// static String imgUrl = "file://" + "/your/path/to/img.png"; // Linux/macOS
// static String imgUrl = "file:///" + "C:/your/path/to/img.png"; // Windows
public static void image2video() throws ApiException, NoApiKeyException, InputRequiredException {
// Set parameters
Map parameters = new HashMap<>();
parameters.put("prompt_extend", true);
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.1-i2v-turbo")
.prompt("a cat running on the grass")
.imgUrl(imgUrl)
.parameters(parameters)
.build();
System.out.println("please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
image2video();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
Sample response
The video_url is valid for 24 hours. Download the video promptly.
{
"request_id": "3171aa20-c479-9dc2-ae55-xxxxxx",
"output": {
"task_id": "8b61b356-45ad-45f3-9be2-xxxxxx",
"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"
}
}
Asynchronous calling
Sample request
// 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 Image2Video {
static {
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// Get DashScope API Key from environment variables (Alibaba Cloud Model Studio API key)
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Image input methods (choose one)
*
* [Method 1] Public URL
*/
static String imgUrl = "https://cdn.translate.alibaba.com/r/wanx-demo-1.png";
/**
* [Method 2] Local file path (file://+absolute path or file:///+absolute path)
*/
// static String imgUrl = "file://" + "/your/path/to/img.png"; // Linux/macOS
// static String imgUrl = "file:///" + "C:/your/path/to/img.png"; // Windows
public static void image2video() throws ApiException, NoApiKeyException, InputRequiredException {
// Set parameters
Map parameters = new HashMap<>();
parameters.put("prompt_extend", true);
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.1-i2v-turbo")
.prompt("a cat running on the grass")
.imgUrl(imgUrl)
.parameters(parameters)
.build();
// Asynchronous call
VideoSynthesisResult task = vs.asyncCall(param);
System.out.println(JsonUtils.toJson(task));
System.out.println("please wait...");
// Obtain the analysis results
// apiKey is already configured in environment variables, so it can be set to null here
VideoSynthesisResult result = vs.wait(task, null);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
image2video();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
Sample response
1. Create task
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}
2. Query task status
The video_url is valid for 24 hours. Please download the video promptly.
{
"request_id": "3d740fc4-a968-9c36-b0e7-xxxxxxxx",
"output": {
"task_id": "34dcf4b0-ed84-441e-91cb-xxxxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxx.mp4?xxxxxx"
},
"usage": {
"video_count": 1,
"video_duration": 5,
"video_ratio": "standard"
}
}
Error codes
If the call failed and returned an error message, see Error messages.
Specific status codes for this API:
HTTP status code | code | message | Description |
400 | InvalidParameter | InvalidParameter | The request parameter is invalid. |
400 | IPInfringementSuspect | Input data is suspected of being involved in IP infringement. | The input data (such as prompts or images) may involve intellectual property infringement. Check your input to ensure it does not contain such content. |
400 | DataInspectionFailed | Input data may contain inappropriate content. | The input data (such as prompts or images) may contain sensitive content. Change your input and try again. |
500 | InternalError | InternalError | A service error occurs. Try again first to rule out occasional issues. |
Billing and rate limiting
Free quota
Overview: Free quota refers to the duration of successfully generated output videos. Abnormal input content and model processing failures do not consume the free quota.
How to claim: You automatically get it after activating Model Studio, valid for 180 days.
Account usage: Alibaba Cloud account and its RAM users share the free quota.
Learn more about New user free quota.
Billing description
When a model has a clear unit price, such as $0.2/second, it has been commercialized. After the free quota is exhausted or expired, you need to pay for usage.
Billing item: Only successfully generated videos are charged. Other situations are not charged.
Payment method: All payments are made by the Alibaba Cloud account. RAM users cannot pay independently. To check your bills, go to Billing Overview.
Recharge: You can recharge on the Expenses and Cost page.
Usage statistics: You can check model usage and call counts on the Model Observation page.
Learn more about Billable items.
Rate limiting
Overview: Alibaba Cloud account and its RAM users share the limits.
Video access
Domain whitelist: Ensure your system can access video links
Generated videos are stored in OSS, and each video is assigned an OSS link, such as https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.mp4
. OSS links allow public access. You can use this link to download the video. The link is valid for only 24 hours.
If your business has high security requirements and cannot access OSS links, you need to configure a separate whitelist for external network access Add the following domains to your whitelist to access video links.
# OSS domain list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com
FAQ
Does the plus model support outputting 480P videos?
No, it does not. To generate videos with 480P resolution, use wan2.1-i2v-turbo
and specify the specific level (such as 480P
) in the resolution
parameter.
The video resolution levels supported by the models are:
wan2.1-i2v-turbo: 480P, 720P.
wan2.1-i2v-plus: 720P.