Wan 2.7 - image-to-video API
The Wan 2.7 image-to-video model supports multimodal input (text, images, audio, and video) and performs three tasks: first-frame-to-video, first-and-last-frame-to-video, and video continuation .
References: User guide
NoteThe newly launched image-to-video API (wan2.7 model) supports all three tasks and is recommended as the first choice.
The earlier image-to-video from first frame API (wan2.6 and earlier models) supports only first-frame-to-video.
Availability
To ensure successful calls, the model, endpoint URL, and API key must all belong to the same region. Cross-region calls fail.
- Select a model: Confirm the region of the model.
- Select a URL: Select the endpoint URL for the region. Both HTTP URLs and DashScope SDK URLs are supported.
- Configure an API key: Obtain an API key for the region, and then configure the API key as an environment variable.
- Install the SDK: To call the API by using an SDK, install the DashScope SDK.
NoteThe sample code in this topic applies to the Beijing region.
ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The dedicated domains deliver superior performance and higher stability for inference requests. We recommend that you migrate to the new domains:
- China (Beijing) region: from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore region: from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which you can view on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domains remain fully functional.
HTTP
ImportantThis API uses the new image-to-video protocol and supports only the wan2.7 model.
Image-to-video tasks take a long time (typically 1 to 5 minutes), so the API uses asynchronous invocation. The entire process consists of two core steps: "create a task -> poll for the result", as follows:
Step 1: Create a task and get the task ID
Beijing
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Replace {WorkspaceId} with your actual workspace ID.
Note
- After the task is created, use the
task_idreturned by the API to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Use polling to retrieve the result. - For beginner guidance, see Postman.
Request parametersContent-Type The request content type. This parameter must be set to Authorization Request authentication. This API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx. X-DashScope-Async The asynchronous processing configuration parameter. HTTP requests support only asynchronous calls, and this parameter must be set to ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request bodymodel The model name. For the list of models and prices, see Model pricing. Example: wan2.7-i2v-2026-04-25. input Basic input information, such as the prompt. parameters Video processing parameters, such as setting the video resolution, setting the video duration, enabling smart prompt rewriting, and adding a watermark. | Video generation from the first frameGenerate a video based on a first frame image and audio. Video generation from the first and last framesPass a first frame and a last frame to generate a video. Video continuationGenerate subsequent content based on an initial video clip. |
Response parametersoutput Task output information. request_id The unique request identifier, which can be used for request tracing and troubleshooting. code The error code returned when the request fails. This parameter is not returned when the request succeeds. For more information, see Error codes. message The detailed error message returned when the request fails. This parameter is not returned when the request succeeds. For more information, see Error codes. | Successful responseSave the task_id, which is used to query the task status and result. Error responseTask creation failed. See Error codes to resolve the issue. |
Step 2: Query the result by task ID
Beijing
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Replace {WorkspaceId} with your actual workspace ID.
Note
- Polling recommendation: Video generation takes several minutes. We recommend that you use a polling mechanism with a reasonable query interval (such as 15 seconds) to obtain the result.
- Task state transition: PENDING (queued) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
- Result link: After the task succeeds, a video URL is returned, which is valid for 24 hours. We recommend that you download the video immediately after obtaining the URL and save it to permanent storage (such as Alibaba Cloud OSS).
- task_id validity: 24 hours. After it expires, the result can no longer be queried, and the API returns the task status as
UNKNOWN. - RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.
- More operations: For operations such as batch queries and task cancellation, see Manage asynchronous tasks.
Request parametersHeadersAuthorization Request authentication. This API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx. Path parameterstask_id The task ID. | Query task resultReplace |
Response parametersoutput Task output information. usage Output statistics, counted only for successful results. request_id The unique request identifier, which can be used for request tracing and troubleshooting. | Task succeededThe video URL is retained for only 24 hours and is automatically cleared after it expires. Save the generated video in a timely manner. Task failedIf the task fails, task_status is set to FAILED, and an error code and message are provided. See Error codes to resolve the issue. Task query expiredThe task_id is valid for queries for 24 hours. After it expires, the result can no longer be queried, and the following error is returned. |
DashScope SDK
The SDK parameter names are basically the same as those of the HTTP API, and the parameter structure is encapsulated based on the features of each language.
Because image-to-video tasks take a long time (typically 1 to 5 minutes), the SDK encapsulates the HTTP asynchronous invocation process at the underlying layer and supports both synchronous and asynchronous invocation methods.
The actual processing time depends on the number of queued tasks and the service execution status. Please wait patiently when obtaining the result.
Python SDK
ImportantMake sure that the DashScope Python SDK version is not lower than 2.0.1 before running the following code.
If the version is too old, errors such as "url error, please check url!" may occur. See Install the SDK to update the SDK.
Set region based on the region of the model (pass it in when constructing the Client; the region value varies by region):
Beijing
region="cn-beijing"
Singapore
region="ap-southeast-1"
Replace {WorkspaceId} with your actual workspace ID.
Synchronous call
Request example
# -*- coding: utf-8 -*-
import dashscope
import os
from dashscope.v2 import DashScopeError
# 以下为华北2(北京)地域的配置,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的region取值不同。
client = dashscope.Client(
# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
media = [
{
"type": "first_frame",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
},
{
"type": "driving_audio",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
}
]
def sample_sync_call():
print('----sync call, please wait a moment----')
# generate 为一步式调用(提交任务并等待完成),返回已完成的 Job
# prompt_extend:1.x 默认开启提示词智能改写;2.0 缺省由服务端决定,此处显式开启保持行为一致
try:
job = client.videos.generate(
model="wan2.7-i2v-2026-04-25",
media=media,
resolution="720P",
duration=10,
watermark=True,
prompt="一幅都市奇幻艺术的场景。一个充满动感的涂鸦艺术角色。一个由喷漆所画成的少年,正从一面混凝土墙上活过来。他一边用极快的语速演唱一首英文rap,一边摆着一个经典的、充满活力的说唱歌手姿势。场景设定在夜晚一个充满都市感的铁路桥下。灯光来自一盏孤零零的街灯,营造出电影般的氛围,充满高能量和惊人的细节。视频的音频部分完全由rap构成,没有其他对话或杂音。",
prompt_extend=True,
)
print(job)
print(job.video_url)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_sync_call()
Response example
The video_url is valid for 24 hours. Download the video in a timely manner.
{
"request_id": "ac5faf37-ddfa-9720-a0c5-xxxxxx",
"task_id": "b97c6d86-ad73-4bb7-80ff-xxxxxx",
"status": "SUCCEEDED",
"video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"duration": 10,
"input_video_duration": 0,
"output_video_duration": 10,
"SR": 720
}
}
Asynchronous call
Request example
# -*- coding: utf-8 -*-
import dashscope
import os
from dashscope.v2 import DashScopeError
# 以下为华北2(北京)地域的配置,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的region取值不同。
client = dashscope.Client(
# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
media = [
{
"type": "first_frame",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
},
{
"type": "driving_audio",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
}
]
def sample_async_call():
# 提交异步任务,立即返回任务信息
# prompt_extend:1.x 默认开启提示词智能改写;2.0 缺省由服务端决定,此处显式开启保持行为一致
try:
job = client.videos.jobs.create(
model="wan2.7-i2v-2026-04-25",
media=media,
resolution="720P",
duration=10,
watermark=True,
prompt="一幅都市奇幻艺术的场景。一个充满动感的涂鸦艺术角色。一个由喷漆所画成的少年,正从一面混凝土墙上活过来。他一边用极快的语速演唱一首英文rap,一边摆着一个经典的、充满活力的说唱歌手姿势。场景设定在夜晚一个充满都市感的铁路桥下。灯光来自一盏孤零零的街灯,营造出电影般的氛围,充满高能量和惊人的细节。视频的音频部分完全由rap构成,没有其他对话或杂音。",
prompt_extend=True,
)
print(job)
print("task_id: %s" % job.task_id)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
return
# 查询任务状态
try:
snapshot = client.videos.jobs.fetch(job.task_id)
print(snapshot.status)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
# 等待任务完成(指数退避轮询,默认总预算24小时)
try:
done = client.videos.jobs.wait(job)
print(done)
print(done.video_url)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_async_call()
Response example
- Response example for creating a task
{
"request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
"task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
"status": "PENDING"
}
- Response example for querying the task result
The video_url is valid for 24 hours. Download the video in a timely manner.
{
"request_id": "ac5faf37-ddfa-9720-a0c5-xxxxxx",
"task_id": "b97c6d86-ad73-4bb7-80ff-xxxxxx",
"status": "SUCCEEDED",
"video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"duration": 10,
"input_video_duration": 0,
"output_video_duration": 10,
"SR": 720
}
}
Java SDK
ImportantMake sure that the DashScope Java SDK version is not lower than 2.22.14 before running the following code.
If the version is too old, errors such as "url error, please check url!" may occur. See Install the SDK to update the SDK.
Set Constants.baseHttpApiUrl based on the region of the model:
Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
Singapore
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
Replace {WorkspaceId} with your actual workspace ID.
Synchronous call
A synchronous call blocks and waits until the video generation is complete and the result is returned.
Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
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.ArrayList;
import java.util.List;
public class Image2Video {
static {
// 以下为华北2(北京)地域的URL。请将 {WorkspaceId} 替换为您的百炼业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void syncCall() {
VideoSynthesis videoSynthesis = new VideoSynthesis();
final String prompt = "一幅都市奇幻艺术的场景。一个充满动感的涂鸦艺术角色。一个由喷漆所画成的少年,正从一面混凝土墙上活过来。他一边用极快的语速演唱一首英文rap,一边摆着一个经典的、充满活力的说唱歌手姿势。场景设定在夜晚一个充满都市感的铁路桥下。灯光来自一盏孤零零的街灯,营造出电影般的氛围,充满高能量和惊人的细节。视频的音频部分完全由他的rap构成,没有其他对话或杂音。";
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png")
.type("first_frame")
.build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3")
.type("driving_audio")
.build());
}};
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.7-i2v-2026-04-25")
.prompt(prompt)
.media(media)
.watermark(true)
.duration(10)
.resolution("720P")
.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();
}
}
Asynchronous call
Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
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.ArrayList;
import java.util.List;
public class Image2Video {
static {
// 以下为华北2(北京)地域的URL。请将 {WorkspaceId} 替换为您的百炼业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() {
VideoSynthesis videoSynthesis = new VideoSynthesis();
final String prompt = "一幅都市奇幻艺术的场景。一个充满动感的涂鸦艺术角色。一个由喷漆所画成的少年,正从一面混凝土墙上活过来。他一边用极快的语速演唱一首英文rap,一边摆着一个经典的、充满活力的说唱歌手姿势。场景设定在夜晚一个充满都市感的铁路桥下。灯光来自一盏孤零零的街灯,营造出电影般的氛围,充满高能量和惊人的细节。视频的音频部分完全由他的rap构成,没有其他对话或杂音。";
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png")
.type("first_frame")
.build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3")
.type("driving_audio")
.build());
}};
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.7-i2v-2026-04-25")
.prompt(prompt)
.media(media)
.watermark(true)
.duration(10)
.resolution("720P")
.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();
}
}
Error codes
If the model call fails and an error message is returned, see Error codes to resolve the issue.
FAQ
Q: How do I generate a video with a specific aspect ratio, such as 3:4?
A: The aspect ratio of the output video is determined by the input material (first frame image or first video clip), but it is not guaranteed to be exactly equal to the input ratio (for example, exactly 3:4). The actual output may deviate slightly.
The following example uses a first frame image as the input to explain the logic:
-
Why does the deviation occur?
- Execution logic: The aspect ratio of the input image is used as the baseline reference, combined with the target total pixels of the
resolutiontier. Because the video width and height must be multiples of 16 (video encoding specification), the system automatically fine-tunes the output to the closest valid resolution. - Calculation example: For a 750×1000 first frame image (aspect ratio 3:4 = 0.75) with resolution set to "720P" (target total pixels of about 920,000), the resolution of the actual output video is 816×1104 (aspect ratio ≈ 0.739, total pixels of about 900,000).
- Execution logic: The aspect ratio of the input image is used as the baseline reference, combined with the target total pixels of the
-
Practical recommendations:
- Input control: Use a first frame or first video clip that matches the target ratio as the input.
- Post-processing: If you have strict aspect ratio requirements, we recommend that you use an editing tool to crop the video or add black bars after the video is generated.
Q: How do I obtain the whitelist of access domain names for video storage?
A: Videos generated by the model are stored in Alibaba Cloud OSS, and the API returns a temporary public URL. If you need to configure a firewall whitelist for this download URL, note the following: The underlying storage changes dynamically based on business conditions. To prevent outdated information from affecting access, this topic does not provide a fixed OSS domain name whitelist. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.