Wan - reference-to-video API reference - Alibaba Cloud Model Studio

References: User guide

Availability

To ensure successful API calls, the model, endpoint URL, and API key must all belong to the same region. Cross-region calls will fail.

Select a model: Confirm the model's region.
Select a URL: Choose the endpoint URL for the corresponding region. HTTP URLs are supported.
Configure an API key: Select a region, get an API key, and configure the API key as an environment variable.

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 API uses the new protocol and supports the wan2.7 model.

Video generation typically takes 1 to 5 minutes, so the API uses asynchronous invocation. The workflow has two steps: create a task, then poll for the result.

Step 1: Create a task and get the task ID

Singapore
Beijing

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace {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 name. For a list of models and their prices, see Model pricing.Example: wan2.7-r2v, wan2.7-r2v-2026-06-12.input object (Required)The basic input information, such as the prompt.

Properties

prompt string (Required)The text prompt describing the desired elements and visual features of the generated video.Supports Chinese and English. Each Chinese character, letter, and punctuation mark counts as one character. Text exceeding the limit is automatically truncated.

wan2.7-r2v, wan2.7-r2v-2026-06-12: Up to 5,000 characters.

Reference identifiers: In prompts, use identifiers such as "Image 1, Image 2" for images and "Video 1, Video 2" for videos. Include a space between the word and the number, and capitalize the first letter. The order of identifiers must match the order of assets in the media array. Images and videos are counted separately, so "Image 1" and "Video 1" can coexist. If there is only one reference image or video, simplify the reference to "the reference image" or "the reference video".Scene description: For example, if reference Image 1 is a cat and Image 2 is a room. To describe the cat playing in the room, you can use two methods. One is to directly use the identifiers, such as "Image 1 is playing in Image 2". The other is to supplement the description with the subject and scene, such as "The cat from Image 1 is playing in the room from Image 2".When the reference image is a multi-panel storyboard, describe the scene in a multi-shot format in the prompt. You do not need to describe every panel — provide key shots, and the model automatically recognizes the panel logic and completes the remaining scenes. For best results, use only one multi-panel image at a time.For tips on using prompts, see Text-to-video/image-to-video prompt guide.negative_prompt string (Optional)A negative prompt describing content to exclude from the generated video. Use this to constrain the output.Supports Chinese and English. Maximum length: 500 characters. Text exceeding the limit is automatically truncated.Example: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions.media array (Required)An array of media assets (images, videos, and audio) used as visual and audio references. Images can include multiple views, commonly used for referencing characters, props, and scenes.

Each element in the array is a media object that contains type and url fields.
The order of elements in the array corresponds to the reference identifiers in the prompt. Images and videos are counted separately, so "Image 1" and "Video 1" can coexist.
- The first reference_video in the array corresponds to Video 1, the second to Video 2, and so on.
- The first reference_image in the array corresponds to Image 1, the second to Image 2, and so on.

Properties

type string (Required)The type of the media asset. Valid values:

reference_image: A reference image that provides the visual reference for a main character (person, animal, or object) or scene.
reference_video: A reference video that provides the visual and voice reference for a main character (person, animal, or object). Avoid using videos of empty scenes.
first_frame: The first frame of the video. The generated video starts from this frame, which typically contains the main character (person, animal, or object). You can combine a first frame with subject references for joint control. Common use cases:
- The subject already appears in the first frame: Use a subject reference to enhance consistency or add a voice reference.
- The subject does not appear in the first frame: Use a subject reference to define the features of a new subject that appears during the video.

Asset limits:

A maximum of 1 first frame image.
At least 1 reference image or reference video. Reference images + Reference videos ≤ 5.
When used for a main character, the reference asset must contain only a single character.

url string (Required)The URL of the media asset. Each value can point to one image or one video.

Pass a reference image (type=reference_image)

The URL or Base64-encoded data of the reference image. The image can be a subject (person, animal, or object) or a background. When it includes a subject, it must contain only one character.Image limits:

Formats: JPEG, JPG, PNG (the alpha channel is not supported), BMP, or WEBP.
Resolution: The width and height must be between 240 and 8,000 pixels.
Aspect ratio: 1:8 to 8:1.
File size: Up to 20 MB.

Supported input formats:

Public URL:
- The HTTP or HTTPS protocol is supported.
- Example: https://xxx/xxx.png.
Base64-encoded image string:
- Data format: data:{MIME_type};base64,{base64_data}.
- Example: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (The encoded string is too long and only a snippet is shown.)
- For more information, see Pass an image.

Pass a reference video (type=reference_video)

The URL of the reference video. The video should include a subject (person, animal, or object). Avoid using videos of backgrounds or empty scenes. When the video includes a subject, it must contain only one character. If the video has audio, the voice can also be referenced.Video limits:

Formats: MP4 or MOV.
Duration: 1 to 30s.
Resolution: The width and height must be between 240 and 4,096 pixels.
Aspect ratio: 1:8 to 8:1.
File size: Up to 100 MB.

Supported input formats:

Public URL:
- The HTTP and HTTPS protocols are supported.
- Example: https://xxx/xxx.mp4.

reference_voice string (Optional)The audio URL specifying the voice for the main character in the reference asset (image or video). Use this parameter with reference_image or reference_video. The audio serves only as a voice reference and does not determine spoken content. For best results, match the language of the reference audio to the language of the prompt.Audio logic:

Default behavior: If reference_video contains audio but reference_voice is not specified, the original video audio is used.
Priority: If both reference_video (with audio) and reference_voice are provided, reference_voice takes precedence and overrides the original video audio.

Audio limits:

Formats: WAV or MP3.
Duration: 1 to 10s.
File size: Up to 15 MB.

Supported input formats:

Public URL:
- The HTTP and HTTPS protocols are supported.
- Example: https://xxx/xxx.mp3.

parameters object (Optional)The video processing parameters, such as the video resolution.

Properties

resolution string (Optional)

The resolution directly affects cost. Confirm the price in the Model Studio console before making a call.

The resolution tier of the generated video. Controls the total pixel count.

wan2.7-r2v, wan2.7-r2v-2026-06-12: Valid values are 720P and 1080P. The default value is 1080P.

ratio string (Optional)The aspect ratio of the generated video.Behavior:

No first frame image provided: The video uses the specified ratio.
First frame image provided: The ratio parameter is ignored. The video matches the aspect ratio of the first frame image.

Valid values:

16:9 (default)
9:16
1:1
4:3
3:4

duration integer (Optional)

Duration directly affects cost. Confirm the model pricing before calling the API.

The duration of the generated video in seconds.

wan2.7-r2v, wan2.7-r2v-2026-06-12: The default value is 5.
- If the reference material includes a video, the value must be an integer from 2 to 10.
- If the reference material does not include a video, the value must be an integer from 2 to 15.

prompt_extendboolean (Optional)Enables prompt rewriting. When enabled, a model rewrites the input prompt before generation. This significantly improves quality for shorter prompts but increases processing time.

true (default)
false

watermark boolean (Optional)Adds a watermark. The watermark text is "AI Generated", placed in the lower-right corner of the video.

false (default)
true

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-subject reference (image + video + voice)
Single-image reference (multi-panel image)

You can pass multiple reference assets (images and videos) and specify a voice to generate a video.

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.7-r2v-2026-06-12",
        "input": {
            "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, '\''The sunshine is so nice today.'\'' Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, '\''That sounds lovely. Can you sing it again?'\''",
            "media": [
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 10,
            "prompt_extend": false,
            "watermark": true
        }
    }'

You can provide a nine-panel reference image to control the story, camera composition, and character design to generate a video.

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.7-r2v-2026-06-12",
        "input": {
            "prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie. The characters are in a cute Q-style but with detailed textures, smooth movements, and vibrant colors. Keep the characters and the forest scene consistent. Do not add text. Atmosphere: Adventurous, light-hearted, mysterious, whimsical. Characters: A young boy explorer with a round hat, backpack, and short cloak. His sidekick: a small flying robot with a round body and glowing blue eyes. Scene: A magical forest with giant tree roots, mushrooms, vines, a treasure cave entrance, and sunbeams. Storyboard: 1. Wide shot: Tall trees and intersecting sunbeams in the magical forest, creating a mysterious and bright environment. 2. Medium shot: The little boy pushes aside vines to explore forward. 3. Medium shot: The little robot flies beside him, scanning ahead with its blue light. 4. Close-up: An old treasure map unfolds in his hands. 5. Close-up: His face lights up with excitement. 6. Action shot: The two jump over tree roots and a small stream, venturing deeper into the forest. 7. Medium shot: A moss-covered treasure chest is revealed behind the vines. 8. Close-up: A golden glow emanates from the edge of the chest. 9. Final shot: The boy and the robot stand before the chest, looking at each other in surprise, filled with a sense of adventure.",
            "media": [
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "duration": 10,
            "prompt_extend": false,
            "watermark": true
        }
    }'

Response parameters

output objectThe output information of the task.

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: Query the result by task ID

Singapore
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.

Query the 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

outputobjectThe output information of the task.

Properties

task_id string (Required)The ID of the task.task_status stringThe task 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 objectOutput statistics. Populated only for successful tasks.

Properties

input_video_duration integerThe duration of the input video, in seconds.output_video_duration integerThe duration of the output video, in seconds.duration integerThe total video duration. Cost is calculated based on this value.Formula: duration = input_video_duration + output_video_duration.SR integerThe resolution tier of the generated video. Example: 720.ratio stringThe aspect ratio of the generated video. Example: 16:9.video_count integerThe number of generated videos. The value is always 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task succeeded
Task failed
Task query expired

Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

{
    "request_id": "52cade0d-905e-9b7d-a01e-xxxxxx",
    "output": {
        "task_id": "18814247-f944-4102-aa4a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-02 22:53:19.537",
        "scheduled_time": "2026-04-02 22:53:30.427",
        "end_time": "2026-04-02 23:00:39.287",
        "orig_prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

The task_id is valid for 24 hours. After this period, queries return the following error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

DashScope SDK

SDK parameter names are largely consistent with the HTTP API. The parameter structure is encapsulated based on language features. Reference-to-video tasks typically take 1 to 5 minutes. The SDK wraps the HTTP asynchronous flow and supports both synchronous and asynchronous calls.

Actual processing time depends on the queue length and service status.

Python SDK

Requires DashScope Python SDK 1.25.16 or later.Older versions may trigger errors such as "url error, please check url!". For update instructions, see Install the SDK.

Set base_http_api_url based on the model's region:

Singapore
Beijing

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Replace {WorkspaceId} with your actual workspace ID.

Synchronous call
Asynchronous call

A synchronous call blocks until video generation completes and returns the result directly.

Request example

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key varies by region. To get an API key, see 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, returns the result directly.
    print('please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        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()

Response example

The video_url is valid for 24 hours. Download the video promptly.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

An asynchronous call returns a task ID immediately. Poll or wait for completion separately.

Request example

import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_r2v():
    # Asynchronous call, returns a task_id.
    rsp = VideoSynthesis.async_call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        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))

    # Get asynchronous task information.
    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 asynchronous 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()

Response example

Response example for creating a 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
}

Response example for querying the task result:
The video_url is valid for 24 hours. Download the video promptly.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Java SDK

Ensure that the DashScope Java SDK version is at least 2.22.14 before you run the following code.Older versions may trigger errors such as "url error, please check url!". For update instructions, see Install the SDK.

Set baseHttpApiUrl based on the model's region:

Singapore
Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Replace {WorkspaceId} with your actual workspace ID.

Synchronous call
Asynchronous call

A synchronous call blocks until video generation completes and returns the result directly.

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.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        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/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .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 {
            ref2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Response example

The video_url is valid for 24 hours. Download the video promptly.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

An asynchronous call returns a task ID immediately. Poll or wait for completion separately.

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.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2VideoAsync {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncRef2video() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
        VideoSynthesis vs = new VideoSynthesis();
        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/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        // Submit the 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 {
            asyncRef2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Response example

Response example for creating a task:

{
    "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
    "output": {
        "task_id": "7277e20e-aa01-4709-xxxxxxxx",
        "task_status": "PENDING"
    }
}

Response example for querying the task result:
The video_url is valid for 24 hours. Download the video promptly.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

FAQ

How do I add a voice to a subject (voice reference)?

Only wan2.7 supports voice reference. In the media object, you can pass an audio URL in the reference_voice parameter to specify a reference voice for a reference image or video.

{
    "media": [
        {
            "type": "reference_image",
            "url": "<URL of the reference image>",
            "reference_voice": "<URL of the audio>"
        },
        {
            "type": "reference_video",
            "url": "<URL of the reference video>",
            "reference_voice": "<URL of the audio>"
        }
    ]
}

​Availability

​HTTP

​Step 1: Create a task and get the task ID

Request parameters

Headers

Request body

Response parameters

​Step 2: Query the result by task ID

Request parameters

Headers

Path parameters

Response parameters

​DashScope SDK

​Python SDK

Request example

Response example

​Java SDK

Request example

Response example

​Error codes

​FAQ

​How do I add a voice to a subject (voice reference)?

Availability

HTTP

Step 1: Create a task and get the task ID

Step 2: Query the result by task ID

DashScope SDK

Python SDK

Java SDK

Error codes

FAQ

How do I add a voice to a subject (voice reference)?