Wan - Reference-to-Video - API reference - Alibaba Cloud Model Studio

Wan-R2V accepts multimodal input (images, videos, and audio) to generate videos featuring one or more characters while preserving their appearance and voice across scenes.

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.

Note

The sample code in this topic applies to the Singapore region.

Important

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 Model Studio console. The existing domain remains fully functional.

HTTP

Important

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

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

Beijing

POST https://{WorkspaceId}.cn-beijing.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 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	Multi-subject reference (image + video + voice) 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 } }' Single-image reference (multi-panel image) 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 } }'
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`. Important 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) Important 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) Important 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_extend `boolean` (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.

Response parameters	Successful 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" }` Error response Task creation failed. See Error codes. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` The output information of the task. Properties task_id `string` The task ID. Valid for queries for 24 hours. task_status `string` The status of the task. Enumeration values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown.
request_id `string` Unique request identifier for tracing and troubleshooting.
code `string` Error code. Returned only for failed requests. See Error codes.
message `string` Detailed error message. Returned only for failed requests. See Error codes.

Step 2: Query the result by task ID

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Beijing

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace {WorkspaceId} with your actual workspace ID.

Note

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_id validity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters	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. `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
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.

Response parameters	Task succeeded 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" } } Task failed 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" } }` Task query expired 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" } }`
output `object` The output information of the task. Properties task_id `string` (Required) The ID of the task. task_status `string` The task status. Enumeration values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown. submit_time `string` The 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 `string` The 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 `string` The 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 `string` URL 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 `string` The original input prompt, corresponding to the request parameter `prompt`. code `string` Error code. Returned only for failed requests. See Error codes. message `string` Detailed error message. Returned only for failed requests. See Error codes.
usage `object` Output statistics. Populated only for successful tasks. Properties input_video_duration `integer` The duration of the input video, in seconds. output_video_duration `integer` The duration of the output video, in seconds. duration `integer` The total video duration. Cost is calculated based on this value. Formula: `duration = input_video_duration + output_video_duration`. SR `integer` The resolution tier of the generated video. Example: 720. ratio `string` The aspect ratio of the generated video. Example: 16:9. video_count `integer` The number of generated videos. The value is always 1.
request_id `string` Unique request identifier for tracing and troubleshooting.

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

Important

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

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

Beijing

dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

Replace {WorkspaceId} with your actual workspace ID.

Synchronous 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"
    }
}

Asynchronous call

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

Important

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

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

Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Replace {WorkspaceId} with your actual workspace ID.

Synchronous 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": ""
}

Asynchronous call

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

Singapore

Beijing

Request parameters

Multi-subject reference (image + video + voice)

Single-image reference (multi-panel image)

Headers

Request body

Response parameters

Successful response

Error response

Step 2: Query the result by task ID

Singapore

Beijing

Request parameters

Query the task result

Headers

Path parameters

Response parameters

Task succeeded

Task failed

Task query expired

DashScope SDK

Python SDK

Singapore

Beijing

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Java SDK

Singapore

Beijing

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Error codes

FAQ

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