The Wan reference-to-video model accepts multimodal input and generates single-character or multi-character interaction videos using people or objects as protagonists.
See also: User guide
Availability
The model, endpoint URL, and API key must belong to the same region. Cross-region calls will fail.
Select a model: Confirm the region of the model.
Select a URL: Use the endpoint URL for the corresponding region. HTTP URLs are supported.
Configure API key: Select a region and Get an API key, then Export API key as an environment variable.
The sample code in this topic applies to the Singapore region.
HTTP
This is a legacy API that only supports wan2.6 models.
Video generation tasks typically take 1–5 minutes. The API uses asynchronous calls with two steps: "create a task -> poll for the result". Details are as follows:
Step 1: Create a task
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
US (Virginia)
POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
China (Beijing)
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/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 Postman.
Request parameters | Multi-character interaction (reference images and videos)Pass image and video URLs through Multi-character interaction (reference videos)Pass multiple video URLs through Single characterPass a single video URL through Generate silent videoOnly To generate silent video, you must explicitly set |
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 model to use. See Model pricing for available models and pricing. Example: wan2.6-r2v-flash. | |
input Input parameters such as the prompt. | |
parameters Video generation parameters such as resolution, prompt rewriting, and watermark. |
Response parameters | Successful responseSave the Error responseTask creation failed. See Error messages. |
output Task output. | |
request_id Unique request identifier for tracing and troubleshooting. | |
code Error code. Returned only for failed requests. See Error messages. | |
message Detailed error message. Returned only for failed requests. See Error messages. |
Step 2: Retrieve task result
Singapore
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
US (Virginia)
GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_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 | Retrieve task resultReplace |
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 expiredThe |
output Task output. | |
usage Usage statistics. Only counts successful results. | |
request_id Unique request identifier for tracing and troubleshooting. |
DashScope SDK
SDK parameters follow the same naming conventions as the HTTP API, with language-specific wrappers.
Reference-to-video tasks typically take 1–5 minutes. The SDK wraps the HTTP asynchronous workflow and supports both synchronous and asynchronous calls.
Actual processing time depends on the task queue and server load.
Python
Make sure your DashScope Python SDK version is 1.25.16 or later before running the following code.
An outdated SDK version may cause errors such as "url error, please check url!". See Install the SDK to update.
Set base_http_api_url based on the model's region:
Singapore
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
China (Beijing)
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
Synchronous
Synchronous calls block until video generation completes and the result is returned.
Request example
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os
# Singapore region URL. Use the URL for your region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If DASHSCOPE_API_KEY is not set, replace the following line with: api_key="sk-xxx"
# API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_sync_call_r2v():
# Synchronous call: blocks until the result is ready
print('please wait...')
rsp = VideoSynthesis.call(
api_key=api_key,
model='wan2.6-r2v-flash',
prompt='Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”',
reference_urls=[
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
],
shot_type='multi',
audio=True,
size='1280*720',
duration=10,
watermark=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_r2v()Asynchronous
Asynchronous calls return a task ID immediately. You must poll or wait for the task to complete.
Request example
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
# Singapore region URL. Use the URL for your region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If DASHSCOPE_API_KEY is not set, replace the following line with: api_key="sk-xxx"
# API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_async_call_r2v_26():
# Asynchronous call: returns a task_id
rsp = VideoSynthesis.async_call(
api_key=api_key,
model='wan2.6-r2v-flash',
prompt='Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”',
reference_urls=[
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
],
shot_type='multi',
audio=True,
size='1280*720',
duration=10,
watermark=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))
# Fetch the task status
status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print(status.output.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
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_r2v_26()Java
Make sure your DashScope Java SDK version is 2.22.14 or later before running the following code.
An outdated SDK version may cause errors such as "url error, please check url!". See Install the SDK to update.
Set baseHttpApiUrl based on the model's region:
Singapore
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
China (Beijing)
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
Synchronous
Synchronous calls block until video generation completes 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.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.ArrayList;
import java.util.List;
public class Ref2Video26 {
static {
// Singapore region URL. Use the URL for your region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If DASHSCOPE_API_KEY is not set, replace the following line with: apiKey="sk-xxx"
// API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void ref2video26() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
List<String> referenceUrls = new ArrayList<>();
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.6-r2v-flash")
.prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
.referenceUrls(referenceUrls)
.shotType(VideoSynthesis.ShotType.MULTI)
.audio(Boolean.TRUE)
.size("1280*720")
.duration(10)
.watermark(Boolean.TRUE)
.build();
System.out.println("please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
ref2video26();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}Asynchronous
Asynchronous calls return a task ID immediately. You must poll or wait for the task to complete.
Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
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.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.ArrayList;
import java.util.List;
public class Ref2Video26Async {
static {
// Singapore region URL. Use the URL for your region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If DASHSCOPE_API_KEY is not set, replace the following line with: apiKey="sk-xxx"
// API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncRef2video26() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
VideoSynthesis vs = new VideoSynthesis();
List<String> referenceUrls = new ArrayList<>();
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.6-r2v-flash")
.prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
.referenceUrls(referenceUrls)
.shotType(VideoSynthesis.ShotType.MULTI)
.audio(Boolean.TRUE)
.size("1280*720")
.duration(10)
.watermark(Boolean.TRUE)
.build();
// Submit an asynchronous task
VideoSynthesisResult result = vs.asyncCall(param);
System.out.println("task_id: " + result.getOutput().getTaskId());
System.out.println(JsonUtils.toJson(result));
// Wait for the task to complete
result = vs.wait(result, null);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncRef2video26();
} catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}Error codes
If the model call fails and returns an error message, see Error messages for resolution.