All Products
Search

This Product

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

    Document Center

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

    Last Updated:Mar 30, 2026

    The Wan - reference-to-video model supports multi-modal input (text, images, and videos) and generates videos featuring one or more characters, supporting single-character performances and multi-character interactive scenes. It also supports intelligent shot division for multi-shot videos.

    References: User guide

    Availability

    The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.

    Note

    Sample codes in this topic apply to the Singapore region.

    HTTP

    Reference-to-video tasks typically take 1 to 5 minutes, so the API uses asynchronous invocation: "Create a task → Poll for the result".

    Step 1: Create a task

    Singapore

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

    Virginia

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

    Beijing

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

    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 a beginner's tutorial, see Use Postman or cURL.

    Request parameters

    Multi-character interaction (reference images and videos)

    Pass image and video URLs in reference_urls and set shot_type to multi to generate a multi-shot video.

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

    Multi-character interaction (reference videos)

    Pass multiple video URLs in reference_urls and set shot_type to multi to generate a multi-shot video.

    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",
    "input": {
        "prompt": "character1 says to character2: “I’ll rely on you tomorrow morning!” character2 replies: “You can count on me!”",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/dlrrly/%E5%B0%8F%E5%A5%B3%E5%AD%A91%E8%8B%B1%E6%96%872.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/fkxknn/%E9%93%83%E9%93%83.mp4"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "shot_type": "multi"
    }
}'

    Single-character role assumption

    Pass a single video URL in reference_urls and set shot_type to multi to generate a multi-shot video.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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",
    "input": {
        "prompt": "character1 drinks bubble tea while dancing impromptu to the music.",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "shot_type":"multi"
    }
}'

    Generate silent video

    Only wan2.6-r2v-flash supports silent videos.

    To generate a silent video, explicitly set parameters.audio = false.

    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 impromptu to the music.",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "shot_type":"multi"
    }
}'
    Request headers

    Content-Type string (Required)

    The content type of the request. Must be application/json.

    Authorization string (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx

    X-DashScope-Async string (Required)

    Enables asynchronous processing. Must be enable as HTTP requests support only asynchronous processing.

    Important

    Returns "current user api does not support synchronous calls" error if not included.

    Request body

    model string (Required)

    The model name. For models and pricing, see Model pricing.

    Example: wan2.6-r2v-flash.

    input object (Required)

    Basic input information, including the prompt.

    Properties

    prompt string (Required)

    Text prompt describing elements and visual features for video generation.

    Supports Chinese and English. Each character, letter, and punctuation mark counts as one character. Text exceeding the limit is auto-truncated.

    • wan2.6-r2v-flash: Maximum length is 1,500 characters.

    • wan2.6-r2v: Maximum length is 1,500 characters.

    Character reference: Use identifiers like "character1" and "character2" to reference characters in reference files. Each reference file (video or image) must contain only one character.

    Example: character1 is happily watching a movie on the sofa.

    For how to use prompts, see Text-to-video/image-to-video prompt guide.

    negative_prompt string (Optional)

    Describes unwanted content in video frames to constrain generation.

    Supports Chinese and English. Maximum 500 characters. Text exceeding the limit is auto-truncated.

    Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.

    reference_urls array[string] (Required)

    Important

    The reference_urls parameter directly affects billing. For billing rules, see Billing and rate limits.

    Array of URLs for uploaded reference files (videos and images) used to extract character appearance and voice for video generation matching the reference features.

    • Each URL points to one image or one video:

      • Images: 0 to 5.

      • Videos: 0 to 3.

      • Total limit: Images + Videos ≤ 5.

    • When providing multiple reference files, their order defines character order: first URL = character1, second = character2, and so on.

    • Each reference file must contain only one main character. For example, character1 is a little girl, and character2 is an alarm clock.

    Supported formats:

    1. Public network URL:

      • Supports HTTP or HTTPS protocols.

      • Example: https://cdn.translate.alibaba.com/xxx.png.

    Requirements for reference videos:

    • Format: MP4, MOV.

    • Duration: 1-30s.

    • Video size: Maximum 100 MB.

    Requirements for reference images:

    • Format: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP.

    • Resolution: Width and height must be 240-8,000 pixels.

    • Image size: Maximum 10 MB.

    Example: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg"].

    Deprecated fields

    reference_video_urls array[string]

    Important

    We recommend using reference_urls instead of reference_video_urls.

    Array of URLs for uploaded reference videos used to extract character appearance and voice for video generation matching the reference features.

    • Up to 3 videos are supported.

    • When you provide multiple videos, their order defines the character order: the first URL corresponds to character1, the second to character2, and so on.

    • Each reference video must contain only one character. E.g., character1 is a little girl and character2 is an alarm clock.

    • URLs support HTTP or HTTPS.

    Requirements for each video:

    • Format: MP4, MOV.

    • Duration: 2-30s.

    • File size: Maximum 100 MB.

    Example: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].

    parameters object (Optional)

    The config parameters, such as video resolution.

    Properties

    size string (Optional)

    Important

    • The size parameter directly affects billing. Cost = Unit price (by resolution) × Duration (seconds). For the same model, 1080P costs more than 720P. Review model pricing before calling the API.

    • Size must be specific values (like 1280*720), not ratios (1:1) or tiers (720P).

    Video resolution in width*height format. Default and available values vary by model:

    • wan2.6-r2v-flash: Default is 1920*1080 (1080P). All 720P and 1080P resolutions are supported.

    • wan2.6-r2v: Default is 1920*1080 (1080P). All 720P and 1080P resolutions are supported.

    720P tier: Available video resolutions and aspect ratios:

    • 1280*720: 16:9.

    • 720*1280: 9:16.

    • 960*960: 1:1.

    • 1088*832: 4:3.

    • 832*1088: 3:4.

    1080P tier: Available video resolutions and aspect ratios:

    • 1920*1080: 16:9.

    • 1080*1920: 9:16.

    • 1440*1440: 1:1.

    • 1632*1248: 4:3.

    • 1248*1632: 3:4.

    duration integer (Optional)

    Important

    The duration parameter directly affects billing. Cost = Unit price (by resolution) × Duration (seconds). Review model pricing before calling the API.

    Video duration in seconds.

    • wan2.6-r2v-flash: Integer between 2 and 10. Default is 5.

    • wan2.6-r2v: Integer between 2 and 10. Default is 5.

    Example: 5.

    shot_type string (Optional)

    Shot type: single continuous shot or multiple changing shots.

    Parameter priority: shot_type > prompt. For example, if shot_type is "single", the model outputs a single-shot video even if the prompt says "generate a multi-shot video".

    Optional values:

    • single (default)

    • multi

    Example: single.

    Note

    Use this parameter for strict control over video narrative structure—e.g., single shots for product showcases or multi-shot sequences for short stories.

    audio boolean (Optional)

    Important

    The audio parameter directly affects billing. Prices differ for videos with and without audio. Review model pricing before calling the API.

    Supported model: wan2.6-r2v-flash.

    Whether to generate video with audio.

    Optional values:

    • true (default)

    • false

    Example: true.

    watermark boolean (Optional)

    Whether to add a watermark ("AI Generated" in lower-right corner).

    • false (default)

    • true

    Example: false.

    seed integer (Optional)

    The random number seed. Must be an integer between 0 and 2147483647.

    If not provided, a random seed is generated. Using a fixed seed improves reproducibility, though results may still vary due to model randomness.

    Example: 12345

    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 to resolve the issue.

    {
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

    output object

    Task output.

    Properties

    task_id string

    The ID of the task. Can be used to query the task for up to 24 hours.

    task_status string

    The status of the task.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    Step 2: Query the result

    Singapore

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

    Virginia

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

    Beijing

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

    Note

    • Polling suggestion: Video generation can take several minutes. Use a polling mechanism with a reasonable query interval, such as 15 seconds, to retrieve the result.

    • Task status transition: PENDING → RUNNING → SUCCEEDED or FAILED.

    • Result URL: After the task is successful, a video URL is returned. The URL is valid for 24 hours. After you retrieve the URL, you must immediately download and save the video to a permanent storage service, such as Object Storage Service (OSS).

    • task_id validity: 24 hours. After this period, you cannot query the result, and the API returns a task status of UNKNOWN.

    Request parameters

    Query task result

    Replace {task_id} with the task_id value returned by the previous API call. task_id is valid for queries within 24 hours.

    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Request headers

    Authorization string (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx

    URL path parameters

    task_id string (Required)

    The ID of the task to query.

    Response parameters

    Task succeeded

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

    {
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 00:25:59.869",
        "scheduled_time": "2025-12-16 00:25:59.900",
        "end_time": "2025-12-16 00:30:35.396",
        "orig_prompt": "character1 is happily watching a movie on the sofa",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
     "usage": {
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 5,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

    Task failed

    When a task fails, task_status is set to FAILED with an error code and message. See error codes to resolve the issue.

    {
    "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 fail and return the following error message.

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

    output object

    Task output.

    Properties

    task_id string (Required)

    The ID of the task to query.

    task_status string

    Task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    submit_time string

    The time when the task was submitted. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    The URL of the generated video. Returned only when task_status is SUCCEEDED.

    URL is valid for 24 hours. Use to download the video in MP4 format with H.264 encoding.

    orig_prompt string

    The original input prompt. This is the value of the prompt request parameter.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    usage object

    Output statistics for successful tasks only.

    Properties

    input_video_duration integer

    Duration of input reference videos in seconds.

    output_video_duration integer

    Duration of the output video in seconds.

    duration float

    Total video duration used for billing.

    Formula: duration = input_video_duration + output_video_duration.

    SR integer

    Resolution tier of the generated video. Example: 720.

    size string

    Resolution of the generated video in "width*height" format. Example: 1280*720.

    video_count integer

    Number of generated videos. Fixed at 1.

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    Limitations

    • Data validity: The task_id and video video_url are retained for 24 hours only. After expiration, they cannot be queried or downloaded.

    • Content moderation: Input prompt and output video undergo content moderation. Requests with non-compliant content return an IPInfringementSuspect or DataInspectionFailed error. For details, see Error messages.

    Error codes

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

    FAQ

    Q: How do I get the domain name whitelist for video storage?

    A: Videos generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.