Alibaba AI Docs

Appearance

Wan - reference-to-video API reference ​

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.

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://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Beijing ​

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisNote

  • 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 Postman.

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
curl --location 'https://dashscope-intl.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",
 "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
curl --location 'https://dashscope-intl.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",
 "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.

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: 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. <li> 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. </li>

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: <li> 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. </li> 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: <li> The HTTP or HTTPS protocol is supported.

  • Example: https://xxx/xxx.png. </li>

  • Base64-encoded image string: <li> 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. </li>

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: <li> The HTTP and HTTPS protocols are supported.

  • Example: https://xxx/xxx.mp4. </li>

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: <li> The HTTP and HTTPS protocols are supported.

  • Example: https://xxx/xxx.mp3. </li>

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: 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 The table below shows the output video resolutions (width × height in pixels) for different aspect ratios.

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: The default value is 5. <li> 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. </li>

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

json
{
 "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 messages.

json
{
 "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 messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

Step 2: Query the result by task ID ​

Singapore ​

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Beijing ​

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_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
curl -X GET https://dashscope-intl.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.

json
{
 "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 messages.

json
{
 "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.

json
{
 "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 messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

usage *object* Output statistics. Populated only for successful tasks. Properties

input_video_duration&nbsp;*integer* The duration of the input video, in seconds.

output_video_duration&nbsp;*integer* The duration of the output video, in seconds.

duration&nbsp;*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&nbsp;*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://dashscope-intl.aliyuncs.com/api/v1'

Beijing ​

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Synchronous call ​

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

Request example ​
HELPCODEESCAPE-python
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os


dashscope.base_http_api_url = 'https://dashscope-intl.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',
        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.

HELPCODEESCAPE-json
{
    "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 ​
HELPCODEESCAPE-python
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope

# The following is the URL for the Singapore region. The URL varies by region.
dashscope.base_http_api_url = 'https://dashscope-intl.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',
        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 ​

  1. Response example for creating a task:

    HELPCODEESCAPE-json
{
    "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
}

  2. Response example for querying the task result:

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

    HELPCODEESCAPE-json
{
    "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://dashscope-intl.aliyuncs.com/api/v1";

Beijing ​

Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";

Synchronous call ​

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

Request example ​
HELPCODEESCAPE-java
// 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 is the URL for the Singapore region. The URL varies by region.
        Constants.baseHttpApiUrl = "https://dashscope-intl.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&lt;VideoSynthesisParam.Media&gt; media = new ArrayList&lt;VideoSynthesisParam.Media&gt;(){​{
            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&lt;String, Object&gt; 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")
                        .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.

HELPCODEESCAPE-json
{
    "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.0,
        "input_video_duration": 5.0,
        "output_video_duration": 10.0,
        "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 ​
HELPCODEESCAPE-java
// 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 is the URL for the Singapore region. The URL varies by region.
        Constants.baseHttpApiUrl = "https://dashscope-intl.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&lt;VideoSynthesisParam.Media&gt; media = new ArrayList&lt;VideoSynthesisParam.Media&gt;(){​{
            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&lt;String, Object&gt; 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")
                        .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 ​

  1. Response example for creating a task:

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

  2. Response example for querying the task result:

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

    HELPCODEESCAPE-json
{
    "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.0,
        "input_video_duration": 5.0,
        "output_video_duration": 10.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Error codes ​

If the model call fails and returns an error message, see Error messages 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.

HELPCODEESCAPE-json
{
    "media": [
        {
            "type": "reference_image",
            "url": "&lt;URL of the reference image&gt;",
            "reference_voice": "&lt;URL of the audio&gt;"
        },
        {
            "type": "reference_video",
            "url": "&lt;URL of the reference video&gt;",
            "reference_voice": "&lt;URL of the audio&gt;"
        }
    ]
}

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio