Skip to main content
Wan - legacy video models

Wan - reference-to-video (2.6)

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.
The sample code in this topic applies to the Singapore region.
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

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
  • US (Virginia)
  • Frankfurt
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisReplace {WorkspaceId} with your actual workspace ID.
  • 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 guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model string (Required)The model to use. See Model pricing for available models and pricing.Example: wan2.6-r2v-flash.input object (Required)Input parameters such as the prompt.

Properties

prompt string (Required)Text prompt describing the desired elements and visual characteristics of the generated video.Supports Chinese and English. Each character counts as one. Content exceeding the limit is automatically truncated.
  • wan2.6-r2v-flash: Maximum length: 1,500 characters.
  • wan2.6-r2v: Maximum length: 1,500 characters.
Character reference: Use identifiers such as "character1, character2" to refer to reference characters. Each reference (video or image) should contain only one character. The model identifies characters in the references only through these identifiers.Example: character1 happily watches a movie on the sofa.For tips on writing prompts, see Text-to-video/image-to-video prompt guide.negative_prompt string (Optional)Negative prompt describing unwanted elements in the video.Supports Chinese and English. Maximum length: 500 characters. Content exceeding the limit is automatically truncated.Example: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions, etc.reference_urls array[string] (Required)
reference_urls directly affects billing. For pricing details, see Billing and rate limiting.
Array of reference file URLs. Supports both video and image inputs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.
  • Each URL can point to one image or one video:
    • Images: 0–5.
    • Videos: 0–3.
    • Total: images + videos ≤ 5.
  • When passing multiple reference files, the array order defines the character order. The first URL maps to character1, the second to character2, and so on.
  • Each reference file should contain only one subject character. For example, character1 is a girl, and character2 is an alarm clock.
Supported formats:
  1. Public URL:
Video requirements:
  • Format: MP4, MOV.
  • Duration: 1s–30s.
  • File size: up to 100 MB.
Image requirements:
  • Format: JPEG, JPG, PNG (no transparency), BMP, WEBP.
  • Resolution: both width and height must be between 240 and 8,000 pixels.
  • File size: up to 20 MB.
Example: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg"].
reference_video_urls array[string]
Use reference_urls instead of reference_video_urls.
Array of reference video URLs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.
  • Up to 3 videos.
  • When passing multiple videos, the array order defines the character order. The first URL maps to character1, the second to character2, and so on.
  • Each reference video should contain only one character (for example, character1 is a girl, and character2 is an alarm clock).
  • URLs support HTTP or HTTPS.
Requirements for each video:
  • Format: MP4, MOV.
  • Duration: 2–30s.
  • File size: up to 100 MB.
Example: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].
parameters object (Optional)Video generation parameters such as resolution, prompt rewriting, and watermark.

Properties

size string (Optional)
  • size directly affects billing. Cost = unit price (based on resolution) x duration (seconds). For the same model, 1080P > 720P. Check Model pricing before calling.
  • size must be an exact value (such as 1280*720), not a ratio or shorthand like 1:1 or 720P.
Resolution of the generated video, in width*height format. The default value and available options depend on the model parameter:
  • wan2.6-r2v-flash: Defaults to 1920*1080 (1080P). Supports all 720P and 1080P resolutions.
  • wan2.6-r2v: Defaults to 1920*1080 (1080P). Supports all 720P and 1080P resolutions.
720P resolutions and their aspect ratios:
  • 1280*720: 16:9.
  • 720*1280: 9:16.
  • 960*960: 1:1.
  • 1088*832: 4:3.
  • 832*1088: 3:4.
1080P resolutions and their aspect ratios:
  • 1920*1080: 16:9.
  • 1080*1920: 9:16.
  • 1440*1440: 1:1.
  • 1632*1248: 4:3.
  • 1248*1632: 3:4.
duration integer (Optional)
duration directly affects billing. Cost = unit price (based on resolution) x duration (seconds). Check Model pricing before calling.
Duration of the generated video, in seconds.
  • wan2.6-r2v-flash: Must be between 2 and 10. Defaults to 5.
  • wan2.6-r2v: Must be between 2 and 10. Defaults to 5.
Example: 5.shot_type string (Optional)Shot composition of the generated video, determining whether the video consists of a single continuous shot or multiple shots.Parameter priority: shot_type > prompt. For example, if shot_type is set to "single", the model outputs a single-shot video even if the prompt says "generate a multi-shot video".Valid values:
  • single: Single-shot video. This is the default.
  • multi: Multi-shot video.
Example: single.
Use this parameter to control the narrative structure of the video, such as single-shot for product showcases or multi-shot for story clips.
audio boolean (Optional)
audio directly affects billing. Videos with and without audio are priced differently. Check Model pricing before calling.
Supported model: wan2.6-r2v-flash.Whether to generate audio in the video.Valid values:
  • true (default)
  • false
Example: true.watermark boolean (Optional)Whether to add a watermark. The watermark appears in the bottom-right corner with the text "AI-generated".
  • false (default)
  • true
Example: false.seed integer (Optional)The random number seed must be an integer in the range [0, 2147483647].If not specified, a random seed is generated. A fixed seed improves reproducibility.Because model generation is probabilistic, the same seed does not guarantee identical results.
  • Multi-character interaction (reference images and videos)
  • Multi-character interaction (reference videos)
  • Single character
  • Generate silent video
Pass image and video URLs through reference_urls. Set shot_type to multi for multi-shot video.
# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-r2v-flash",
    "input": {
        "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"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "audio": true,
        "shot_type": "multi",
        "watermark": true
    }
}'

Response parameters

output objectTask output.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error 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"
}

Step 2: Retrieve task result

  • Singapore
  • US (Virginia)
  • Frankfurt
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Replace {WorkspaceId} with your actual workspace 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 as UNKNOWN.

Request parameters

Headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Path parameters
task_id string (Required)The ID of the task.
  • Retrieve task result
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobjectTask output.

Properties

task_id string (Required)The ID of the task.task_status stringTask status.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
submit_time stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL of the generated video. Returned only when task_status is SUCCEEDED.Valid for 24 hours. The video is in MP4 format with H.264 encoding.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectUsage statistics. Only counts successful results.

Properties

input_video_duration integerDuration of the input reference video, in seconds.output_video_duration integerDuration of the output video, in seconds.duration floatTotal video duration. Billing is based on this value.Formula: duration = input_video_duration + output_video_duration.SR integerResolution tier of the generated video. Example: 720.size stringResolution of the generated video in width*height format. Example: 1280*720.video_count integerNumber of generated videos. Always 1.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
  • Task expired
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.
{
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 00:25:59.869",
        "scheduled_time": "2025-12-16 00:25:59.900",
        "end_time": "2025-12-16 00:30:35.396",
        "orig_prompt": "character1 happily watches a movie on the sofa",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
     "usage": {
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 5,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

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
  • China (Beijing)
  • Frankfurt
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Replace {WorkspaceId} with your actual workspace ID.
  • Synchronous
  • Asynchronous
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://{WorkspaceId}.ap-southeast-1.maas.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()

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
  • China (Beijing)
  • Frankfurt
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Replace {WorkspaceId} with your actual workspace ID.
  • Synchronous
  • Asynchronous
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://{WorkspaceId}.ap-southeast-1.maas.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);
    }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
Text Generation
Image Generation
  • FAQ
Audio
Realtime API
Text Embedding
Model Production