Alibaba Cloud Model Studio:Reference-to-video

Global

Access point and data storage in US (Virginia). Inference compute is dynamically scheduled worldwide. See Global deployment mode.

International

Access point and data storage in Singapore. Inference compute is dynamically scheduled worldwide, excluding Chinese mainland. See International deployment mode.

Chinese mainland

Access point and data storage in Beijing. Inference compute is restricted to Chinese mainland. See Chinese Mainland deployment mode.

Reference input limits

Input method: public URL (HTTP or HTTPS).

Character referencing

Character identifiers map to reference_urls array positions:

"reference_urls": [
    "https://example.com/person-a.mp4",   // character1
    "https://example.com/person-b.mp4",   // character2
    "https://example.com/guitar.png"      // character3
]

Use these identifiers in your prompt: *"character1 plays guitar while character2 sings along, holding character3."*

Example: Four-reference scene

Prompt: *"character2 sits on a chair by the window, holding character3, and plays a soothing American country folk song next to character4. character1 says to character2: 'that sounds great'"*

Input	Type	Reference
wan-r2v-role1.mp4	Video	character1 (person)
wan-r2v-role2.mp4	Video	character2 (person)
	Image	character3 (object)
	Image	character4 (background)

Output: Multi-shot video with audio

Example: Two-character dialogue

Prompt: *"character1 says to character2: 'I'll rely on you tomorrow morning!' character2 replies: 'You can count on me!'"*

Output: Multi-shot video with audio

Sample code (curl)

All examples use the X-DashScope-Async: enable header to submit asynchronous tasks.

Step 1: Submit the task

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.6-r2v-flash",
    "input": {
        "prompt": "Character2 sits on a chair by the window, holding character3, and plays a soothing American country folk song next to character4. Character1 says to Character2: \"that sounds great\"",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "audio": true,
        "shot_type": "multi",
        "watermark": true
    }
}'

Step 2: Retrieve the result

Replace <task-id> with the task_id from the Step 1 response.

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/<task-id> \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Sample code (Python)

This example submits a multi-character task and polls until the result is ready.

import os
import time
import requests

API_KEY = os.environ.get("DASHSCOPE_API_KEY")
BASE_URL = "https://dashscope-intl.aliyuncs.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
}

# Step 1: Submit the task
payload = {
    "model": "wan2.6-r2v-flash",
    "input": {
        "prompt": (
            'Character2 sits on a chair by the window, holding character3, '
            'and plays a soothing American country folk song next to character4. '
            'Character1 says to Character2: "that sounds great"'
        ),
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
        ],
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "audio": True,
        "shot_type": "multi",
        "watermark": True,
    },
}

response = requests.post(
    f"{BASE_URL}/services/aigc/video-generation/video-synthesis",
    headers=headers,
    json=payload,
)
result = response.json()
task_id = result["output"]["task_id"]
print(f"Task submitted: {task_id}")

# Step 2: Poll for the result
poll_headers = {"Authorization": f"Bearer {API_KEY}"}

while True:
    status_response = requests.get(
        f"{BASE_URL}/tasks/{task_id}", headers=poll_headers
    )
    status = status_response.json()
    task_status = status["output"]["task_status"]

    if task_status == "SUCCEEDED":
        video_url = status["output"]["video_url"]
        print(f"Video ready: {video_url}")
        break
    elif task_status == "FAILED":
        print(f"Task failed: {status['output'].get('message', 'Unknown error')}")
        break
    else:
        print(f"Status: {task_status} -- waiting 10s...")
        time.sleep(10)

Example: Holiday unboxing video

Prompt: *"Create a festive holiday unboxing experience. Shot 1 [0-2s]: Character1 sits by a beautifully decorated Christmas tree with twinkling lights, holding a wrapped gift box with elegant red and gold wrapping. Shot 2 [2-4s]: Close-up as Character1 carefully unwraps the gift, revealing premium skincare products inside. Shot 3 [4-6s]: Character1 applies the product with delight, saying: 'This holiday glow is exactly what I wanted!' Shot 4 [6-10s]: Character1 admires their radiant skin in a handheld mirror, surrounded by festive decorations, ending with a warm smile to camera."*

Sample code (curl)

Step 1: Submit the task

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.6-r2v-flash",
    "input": {
        "prompt": "Create a festive holiday unboxing experience.Shot 1 [0-2s]: Character1 sits by a beautifully decorated Christmas tree with twinkling lights, holding a wrapped gift box with elegant red and gold wrapping. Shot 2 [2-4s]: Close-up as Character1 carefully unwraps the gift, revealing premium skincare products inside. Shot 3 [4-6s]: Character1 applies the product with delight, saying: \"This holiday glow is exactly what I wanted!\" Shot 4 [6-10s]: Character1 admires their radiant skin in a handheld mirror, surrounded by festive decorations, ending with a warm smile to camera.",
        "reference_urls":["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mjgmzx/wan-r2v-role-4.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "shot_type":"multi",
        "watermark": true
    }
}'

Step 2: Retrieve the result

Replace <task-id> with the task_id from the Step 1 response.

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/<task-id> \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Example: Silent dance video

Prompt: *"character1 drinks bubble tea while dancing spontaneously to the music."*

Sample code (curl)

Step 1: Submit the task

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.6-r2v-flash",
    "input": {
        "prompt": "character1 drinks bubble tea while dancing spontaneously to the music.",
        "reference_urls":["https://cdn.wanx.aliyuncs.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "shot_type":"multi",
        "audio": false,
        "watermark": true
    }
}'

Step 2: Retrieve the result

Replace <task-id> with the task_id from the Step 1 response.

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/<task-id> \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Billing rules

Videos with audio and silent videos are priced differently. For example, wan2.6-r2v-flash has separate rates for each.

Total billed duration = Input video duration (capped at 5s) + Output video duration

How input video duration is billed

The 5-second cap is distributed evenly across all references. Each video is billed for min(actual duration, truncation limit). Images are free.

Example: 3 references (1 image + 2 videos) with a 1.65s truncation limit per video:

Billed input duration = min(video 1 duration, 1.65s) + min(video 2 duration, 1.65s). The image is not billed.

How do I set the video aspect ratio?

Use the size parameter. Each resolution maps to a fixed aspect ratio -- for example, size=1280*720 produces 16:9. See the size parameter reference for all options.

How do I reference characters in the prompt?

Each reference must contain one character. Use character1, character2, etc. -- identifiers map to the URL order in reference_urls:

"reference_urls": [
    "https://example.com/girl.mp4",   // character1
    "https://example.com/clock.png"   // character2
]

What happens when a task fails?

Poll the task status endpoint. If task_status is FAILED, check the message field for error details. Common causes: invalid reference URLs, unsupported file formats, or exceeded rate limits. Failed tasks are not billed.