# Wan - reference-to-video (2.6)

> The Wan reference-to-video model accepts multimodal input and generates single-character or multi-character interaction videos using people or objects as protagonists.

<strong>See also</strong>: [User guide](/help/en/model-studio/video-to-video-guide)

## Availability <span id="1fd78afa5brlj" /> <span id="09a068c6b1q5b" />

The model, endpoint URL, and API key must belong to the <strong>same region</strong>. Cross-region calls will fail.

- [<strong>Select a model</strong>](/help/en/model-studio/video-to-video-guide#06f39eafa2dwt): Confirm the region of the model.
- <strong>Select a URL</strong>: Use the endpoint URL for the corresponding region. HTTP URLs are supported.
- <strong>Configure API key</strong>: Select a region and [Obtain an API key](/help/en/model-studio/get-api-key), then [Configure API key as an environment variable](/help/en/model-studio/get-api-key).

<Note>
  The sample code in this topic applies to the <strong>Singapore region</strong>.
</Note>

<Tip>
  Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. <strong>The new dedicated domains deliver superior performance and higher stability for inference requests</strong>. 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 <strong>Workspace Details</strong> page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.
</Tip>

## HTTP <span id="42703589880ts" /> <span id="7c782df20fkq8" />

<Tip>
  This is a <strong>legacy API</strong> that only supports <strong>wan2.6 models</strong>.
</Tip>

Video generation tasks typically take 1–5 minutes. The API uses asynchronous calls with two steps: <strong>"create a task -> poll for the result"</strong>. Details are as follows:

### Step 1: Create a task <span id="81185ac18blmj" /> <span id="976fdf90ddqx7" />

<Tabs>
  <Tab title="Singapore">
    `POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="US (Virginia)">
    `POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`
  </Tab>

  <Tab title="Frankfurt">
    `POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="China (Beijing)">
    `POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>
</Tabs>

<Note>
  - After the task is created, use the returned `task_id` to query the result. The `task_id` is valid for 24 hours. <strong>Do not create duplicate tasks</strong>. Instead, use polling to retrieve the result.
  - For guidance for beginners, see [Call APIs with Postman or cURL](/help/en/model-studio/first-call-to-image-and-video-api).
</Note>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Request parameters <span id="afcd41d2b57zf" />

        ##### Headers <span id="79473e45c592d" />

        <strong>Content-Type</strong> `string` <strong>(Required)</strong>

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

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        <strong>X-DashScope-Async</strong> `string` <strong>(Required)</strong>

        Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be `enable`.

        <Tip>
          If this request header is missing, the error "current user api does not support synchronous calls" is returned.
        </Tip>

        ##### Request body <span id="66a778d4fbfub" />

        <strong>model</strong> `string` <strong>(Required)</strong>

        The model to use. See [Model pricing](/help/en/model-studio/model-pricing) for available models and pricing.

        Example: wan2.6-r2v-flash.

        <strong>input</strong> `object` <strong>(Required)</strong>

        Input parameters such as the prompt.

        <Accordion title="Properties" defaultOpen>
          <strong>prompt</strong> `string` <strong>(Required)</strong>

          Text prompt describing the desired elements and visual characteristics of the generated video.

          Supports Chinese and English. Each character counts as one. Content exceeding the limit is automatically truncated.

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

          Character reference: Use identifiers such as "<strong>character1, character2</strong>" to refer to reference characters. Each reference (video or image) should contain only one character. The model identifies characters in the references only through these identifiers.

          Example: character1 happily watches a movie on the sofa.

          For tips on writing prompts, see [Text-to-video/image-to-video prompt guide](/help/en/model-studio/text-to-video-prompt).

          <strong>negative\_prompt</strong> `string` (Optional)

          Negative prompt describing unwanted elements in the video.

          Supports Chinese and English. Maximum length: 500 characters. Content exceeding the limit is automatically truncated.

          Example: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions, etc.

          <strong>reference\_urls</strong> `array[string]` <strong>(Required)</strong>

          <Tip>
            reference\_urls directly affects billing. For pricing details, see [Billing and rate limiting](/help/en/model-studio/video-to-video-guide#6f5774ce5fqie).
          </Tip>

          Array of reference file URLs. Supports both video and image inputs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.

          - Each URL can point to <strong>one image</strong> or <strong>one video</strong>:

            - Images: 0–5.
            - Videos: 0–3.
            - Total: images + videos ≤ 5.
          - When passing multiple reference files, the array order defines the character order. The first URL maps to character1, the second to character2, and so on.
          - Each reference file should contain only one subject character. For example, character1 is a girl, and character2 is an alarm clock.

          Supported formats:

          1. Public URL:

             - Supports HTTP or HTTPS.
             - Example: <a href="https://cdn.translate.alibaba.com/xxx.png">[https://cdn.translate.alibaba.com/xxx.png](https://cdn.translate.alibaba.com/xxx.png)</a>.

          Video requirements:

          - Format: MP4, MOV.
          - Duration: 1s–30s.
          - File size: up to 100 MB.

          Image requirements:

          - Format: JPEG, JPG, PNG (no transparency), BMP, WEBP.
          - Resolution: both width and height must be between 240 and 8,000 pixels.
          - File size: up to 20 MB.

          Example: \["<a href="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4">[https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4)</a>", "<a href="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg">[https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg)</a>"].

          <Accordion title="Deprecated">
            <strong>reference\_video\_urls</strong> `array[string]`

            <Tip>
              Use `reference_urls` instead of `reference_video_urls`.
            </Tip>

            Array of reference video URLs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.

            - Up to <strong>3 videos</strong>.
            - When passing multiple videos, the array order defines the character order. The first URL maps to character1, the second to character2, and so on.
            - Each reference video should contain only one character (for example, character1 is a girl, and character2 is an alarm clock).
            - URLs support HTTP or HTTPS.

            Requirements for each video:

            - Format: MP4, MOV.
            - Duration: 2–30s.
            - File size: up to 100 MB.

            Example: \["<a href="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4">[https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4)</a>"].
          </Accordion>
        </Accordion>

        <strong>parameters</strong> `object` (Optional)

        Video generation parameters such as resolution, prompt rewriting, and watermark.

        <Accordion title="Properties" defaultOpen>
          <strong>size</strong> `string` (Optional)

          <Tip>
            - size directly affects billing. Cost = unit price (based on resolution) x duration (seconds). For the same model, 1080P > 720P. Check [Model pricing](/help/en/model-studio/model-pricing) before calling.
            - size must be an exact value (such as `1280*720`), not a ratio or shorthand like 1:1 or 720P.
          </Tip>

          Resolution of the generated video, in `width*height` format. The default value and available options depend on the model parameter:

          - wan2.6-r2v-flash: Defaults to `1920*1080` (1080P). Supports all 720P and 1080P resolutions.
          - wan2.6-r2v: Defaults to `1920*1080` (1080P). Supports all 720P and 1080P resolutions.

          720P resolutions and their aspect ratios:

          - `1280*720`: 16:9.
          - `720*1280`: 9:16.
          - `960*960`: 1:1.
          - `1088*832`: 4:3.
          - `832*1088`: 3:4.

          1080P resolutions and their aspect ratios:

          - `1920*1080`: 16:9.
          - `1080*1920`: 9:16.
          - `1440*1440`: 1:1.
          - `1632*1248`: 4:3.
          - `1248*1632`: 3:4.

          <strong>duration</strong> `integer` (Optional)

          <Tip>
            duration directly affects billing. Cost = unit price (based on resolution) x duration (seconds). Check [Model pricing](/help/en/model-studio/model-pricing) before calling.
          </Tip>

          Duration of the generated video, in seconds.

          - wan2.6-r2v-flash: Must be between 2 and 10. Defaults to `5`.
          - wan2.6-r2v: Must be between 2 and 10. Defaults to `5`.

          Example: 5.

          <strong>shot\_type</strong> `string` (Optional)

          Shot composition of the generated video, determining whether the video consists of a single continuous shot or multiple shots.

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

          Valid values:

          - single: Single-shot video. This is the default.
          - multi: Multi-shot video.

          Example: single.

          <Note>
            Use this parameter to control the narrative structure of the video, such as single-shot for product showcases or multi-shot for story clips.
          </Note>

          <strong>audio</strong> `boolean` (Optional)

          <Tip>
            audio directly affects billing. Videos with and without audio are priced differently. Check [Model pricing](/help/en/model-studio/model-pricing) before calling.
          </Tip>

          <strong>Supported model: wan2.6-r2v-flash.</strong>

          Whether to generate audio in the video.

          Valid values:

          - true (default)
          - false

          Example: true.

          <strong>watermark</strong> `boolean` (Optional)

          Whether to add a watermark. The watermark appears in the bottom-right corner with the text "AI-generated".

          - false (default)
          - true

          Example: false.

          <strong>seed</strong> `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.
        </Accordion>
      </td>

      <td>
        <Tabs>
          <Tab title="Multi-character interaction (reference images and videos)">
            Pass image and video URLs through `reference_urls`. Set `shot_type` to `multi` for multi-shot video.

            ```bash
            # The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
            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.6-r2v-flash",
                "input": {
                    "prompt": "Character2 sits in a chair by the window, 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
                }
            }'
            ```
          </Tab>

          <Tab title="Multi-character interaction (reference videos)">
            Pass multiple video URLs through `reference_urls`. Set `shot_type` to `multi` for multi-shot video.

            ```bash
            # The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
            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.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"
                }
            }'
            ```
          </Tab>

          <Tab title="Single character">
            Pass a single video URL through `reference_urls`. Set `shot_type` to `multi` for multi-shot video.

            ```bash
            # The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
            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.6-r2v",
                "input": {
                    "prompt": "character1 sips milk tea while dancing freestyle to the music.",
                    "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
                },
                "parameters": {
                    "size": "1280*720",
                    "duration": 5,
                    "shot_type":"multi"
                }
            }'
            ```
          </Tab>

          <Tab title="Generate silent video">
            Only `wan2.6-r2v-flash` supports silent video generation.

            To generate silent video, you <strong>must explicitly set</strong> `parameters.audio = false`.

            ```bash
            # The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
            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.6-r2v-flash",
                "input": {
                    "prompt": "character1 sips milk tea while dancing freestyle 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"
                }
            }'
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Response parameters <span id="cd3063363egdc" /> <span id="f5d1a44542v6q" />

        <strong>output</strong> `object`

        Task output.

        <Accordion title="Properties" defaultOpen>
          <strong>task\_id</strong> `string`

          The task ID. Valid for queries for 24 hours.

          <strong>task\_status</strong> `string`

          The status of the task.

          <Accordion title="Enumeration values" defaultOpen>
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELED
            - UNKNOWN: The task does not exist or its status is unknown.
          </Accordion>
        </Accordion>

        <strong>request\_id</strong> `string`

        Unique request identifier for tracing and troubleshooting.

        <strong>code</strong> `string`

        Error code. Returned only for failed requests. See [Error codes](/help/en/model-studio/error-code).

        <strong>message</strong> `string`

        Detailed error message. Returned only for failed requests. See [Error codes](/help/en/model-studio/error-code).
      </td>

      <td>
        <Tabs>
          <Tab title="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"
            }
            ```
          </Tab>

          <Tab title="Error response">
            Task creation failed. See [Error codes](/help/en/model-studio/error-code).

            ```json
            {
                "code": "InvalidApiKey",
                "message": "Invalid API-key provided.",
                "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

### Step 2: Retrieve task result <span id="420e6e77a17om" /> <span id="9247e8b39fpqj" />

<Tabs>
  <Tab title="Singapore">
    `GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="US (Virginia)">
    `GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`
  </Tab>

  <Tab title="Frankfurt">
    `GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="China (Beijing)">
    `GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>
</Tabs>

<Note>
  - <strong>Polling recommendation</strong>: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
  - <strong>Task state transition</strong>: PENDING → RUNNING → SUCCEEDED or FAILED.
  - <strong>Result link</strong>: After a task succeeds, a video URL valid for <strong>24 hours</strong> is returned. Download and save the video to permanent storage, such as [OSS](https://www.alibabacloud.com/help/en/doc-detail/31817.htm).
  - `task_id`<strong>validity</strong>: <strong>24 hours</strong>. After this period, queries return the task status as `UNKNOWN`.
</Note>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Request parameters <span id="a9e0408c70ylw" /> <span id="b43fdb7196o58" />

        ##### Headers <span id="2d2fb41da6idy" />

        <strong>Authorization</strong> `string` <strong>(Required)</strong>

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

        ##### Path parameters <span id="031d8a0fafqhp" />

        <strong>task\_id</strong> `string` <strong>(Required)</strong>

        The ID of the task.
      </td>

      <td>
        <Tabs>
          <Tab title="Retrieve task result">
            Replace `{task_id}` with the `task_id` value returned by the previous API call. The `task_id` is valid for queries for 24 hours, Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).

            ```bash
            curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
            --header "Authorization: Bearer $DASHSCOPE_API_KEY"
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

<table bordertype="no-border" style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "50%" }} />

    <col style={{ width: "50%" }} />
  </colgroup>

  <tbody>
    <tr>
      <td>
        #### Response parameters <span id="810682d979i8q" /> <span id="209bb8b8c8976" />

        <strong>output</strong>`object`

        Task output.

        <Accordion title="Properties" defaultOpen>
          <strong>task\_id</strong> `string` <strong>(Required)</strong>

          The ID of the task.

          <strong>task\_status</strong> `string`

          Task status.

          <Accordion title="Enumeration values" defaultOpen>
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELED
            - UNKNOWN: The task does not exist or its status is unknown.
          </Accordion>

          <strong>submit\_time</strong> `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.

          <strong>scheduled\_time</strong> `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.

          <strong>end\_time</strong> `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.

          <strong>video\_url</strong> `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.

          <strong>orig\_prompt</strong> `string`

          The original input prompt, corresponding to the request parameter `prompt`.

          <strong>code</strong> `string`

          Error code. Returned only for failed requests. See [Error codes](/help/en/model-studio/error-code).

          <strong>message</strong> `string`

          Detailed error message. Returned only for failed requests. See [Error codes](/help/en/model-studio/error-code).
        </Accordion>

        <strong>usage</strong> `object`

        Usage statistics. Only counts successful results.

        <Accordion title="Properties" defaultOpen>
          <strong>input\_video\_duration</strong> `integer`

          Duration of the input reference video, in seconds.

          <strong>output\_video\_duration</strong> `integer`

          Duration of the output video, in seconds.

          <strong>duration</strong> `float`

          Total video duration. Billing is based on this value.

          Formula: `duration = input_video_duration + output_video_duration`.

          <strong>SR</strong> `integer`

          Resolution tier of the generated video. Example: 720.

          <strong>size</strong> `string`

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

          <strong>video\_count</strong> `integer`

          Number of generated videos. Always 1.
        </Accordion>

        <strong>request\_id</strong> `string`

        Unique request identifier for tracing and troubleshooting.
      </td>

      <td>
        <Tabs>
          <Tab title="Task succeeded">
            Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

            ```json
            {
                "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 happily watches 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
                }
            }
            ```
          </Tab>

          <Tab title="Task failed">
            When a task fails, `task_status` is FAILED with an error code and message. See [Error codes](/help/en/model-studio/error-code).

            ```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"
                }
            }
            ```
          </Tab>

          <Tab title="Task 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"
                }
            }
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>

## DashScope SDK <span id="r2v702a0h2sdk" /> <span id="r2v701a0secsd" />

SDK parameters follow the same naming conventions as the [HTTP API](/help/en/model-studio/legacy-wan-reference-to-video-api-reference#42703589880ts), with language-specific wrappers.

Reference-to-video tasks typically take 1–5 minutes. The SDK wraps the HTTP asynchronous workflow and supports both synchronous and asynchronous calls.

> Actual processing time depends on the task queue and server load.

### Python <span id="29484e9a6a0qr" /> <span id="ee3bb3a4c473w" />

<Tip>
  Make sure your DashScope Python SDK version is <strong>2.0.1</strong> or later before running the following code.

  An outdated SDK version may cause errors such as "url error, please check url!". See [Install the SDK](/help/en/model-studio/install-sdk) to update.
</Tip>

Set `region` based on the model's region (passed in when constructing the Client; the region value varies by region):

<Tabs>
  <Tab title="Singapore">
    `region="ap-southeast-1"`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="China (Beijing)">
    `region="cn-beijing"`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="Frankfurt">
    `region="eu-central-1"`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Synchronous">
    Synchronous calls block until video generation completes and the result is returned.

    ##### Request example <span id="r2v741a6h5rq01" /> <span id="r2v741a5secrq1" />

    ```python expandable
    import dashscope
    import os
    from dashscope.v2 import DashScopeError

    # The following is the configuration for the Singapore (ap-southeast-1) region. Replace {WorkspaceId} with your Model Studio workspace ID. The region value varies by region.
    client = dashscope.Client(
        # If DASHSCOPE_API_KEY is not set, replace the following line with: api_key="sk-xxx"
        # API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/model-studio/get-api-key
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    def sample_sync_call_r2v():
        # Synchronous call: blocks until the result is ready; generate is a one-step call (submits the task and waits for completion) that returns a completed Job.
        print('please wait...')
        try:
            job = client.videos.generate(
                model='wan2.6-r2v-flash',
                prompt='Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”',
                # reference_urls is an input-section field, not in the named signature; pass it through extra_input.
                # shot_type and audio are parameters-section fields and are passed through parameters.
                extra_input={'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"
                ]},
                size='1280*720',
                duration=10,
                watermark=True,
                parameters={'shot_type': 'multi', 'audio': True})
            print(job)
            print(job.video_url)
        except DashScopeError as e:
            print(f"HTTP status code: {e.status_code}")
            print(f"Error code: {e.code}")
            print(f"Error message: {e.message}")
            print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

    if __name__ == '__main__':
        sample_sync_call_r2v()
    ```
  </Tab>

  <Tab title="Asynchronous">
    Asynchronous calls return the task ID immediately; use fetch to check the task status, or call wait to block until the task completes (with automatic polling).

    ##### Request example <span id="r2v747a7h5rq02" /> <span id="r2v747a6secrq2" />

    ```python expandable
    import os
    import dashscope
    from dashscope.v2 import DashScopeError

    # The following is the configuration for the Singapore (ap-southeast-1) region. Replace {WorkspaceId} with your Model Studio workspace ID. The region value varies by region.
    client = dashscope.Client(
        # If DASHSCOPE_API_KEY is not set, replace the following line with: api_key="sk-xxx"
        # API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/model-studio/get-api-key
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    def sample_async_call_r2v_26():
        # Asynchronous call: returns a task_id
        try:
            job = client.videos.jobs.create(
                model='wan2.6-r2v-flash',
                prompt='Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”',
                # reference_urls is an input-section field, not in the named signature; pass it through extra_input.
                # shot_type and audio are parameters-section fields and are passed through parameters.
                extra_input={'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"
                ]},
                size='1280*720',
                duration=10,
                watermark=True,
                parameters={'shot_type': 'multi', 'audio': True})
            print(job)
            print("task_id: %s" % job.task_id)
        except DashScopeError as e:
            print(f"HTTP status code: {e.status_code}")
            print(f"Error code: {e.code}")
            print(f"Error message: {e.message}")
            print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
            return

        # Fetch the task status
        try:
            snapshot = client.videos.jobs.fetch(job.task_id)
            print(snapshot.status)
        except DashScopeError as e:
            print(f"HTTP status code: {e.status_code}")
            print(f"Error code: {e.code}")
            print(f"Error message: {e.message}")
            print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

        # Wait for the task to complete (exponential backoff polling, default total budget of 24 hours)
        try:
            done = client.videos.jobs.wait(job)
            print(done)
            print(done.video_url)
        except DashScopeError as e:
            print(f"HTTP status code: {e.status_code}")
            print(f"Error code: {e.code}")
            print(f"Error message: {e.message}")
            print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

    if __name__ == '__main__':
        sample_async_call_r2v_26()
    ```
  </Tab>
</Tabs>

### Java <span id="3f41c60916y03" /> <span id="r2v801a0secjv" />

<Tip>
  Make sure your DashScope Java SDK version is <strong>2.22.14</strong> or later before running the following code.

  An outdated SDK version may cause errors such as "url error, please check url!". See [Install the SDK](/help/en/model-studio/install-sdk) to update.
</Tip>

Set `baseHttpApiUrl` based on the model's region:

<Tabs>
  <Tab title="Singapore">
    `Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="China (Beijing)">
    `Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>

  <Tab title="Frankfurt">
    `Constants.baseHttpApiUrl = "https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1";`

    Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/regions#h2_migrate_domain).
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Synchronous">
    Synchronous calls block until video generation completes and the result is returned.

    ##### Request example <span id="r2v832a7h5jr01" /> <span id="r2v832a6secrq1" />

    ```java expandable
    // 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.List;

    public class Ref2Video26 {

        static {
            // Singapore region URL. Use the URL for your region.
            Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        }

        // If DASHSCOPE_API_KEY is not set, replace the following line with: apiKey="sk-xxx"
        // API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/model-studio/get-api-key
        public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

        public static void ref2video26() throws ApiException, NoApiKeyException, InputRequiredException {
            VideoSynthesis vs = new VideoSynthesis();
            List<String> referenceUrls = new ArrayList<>();
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");

            VideoSynthesisParam param =
                    VideoSynthesisParam.builder()
                            .apiKey(apiKey)
                            .model("wan2.6-r2v-flash")
                            .prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
                            .referenceUrls(referenceUrls)
                            .shotType(VideoSynthesis.ShotType.MULTI)
                            .audio(Boolean.TRUE)
                            .size("1280*720")
                            .duration(10)
                            .watermark(Boolean.TRUE)
                            .build();
            System.out.println("please wait...");
            VideoSynthesisResult result = vs.call(param);
            System.out.println(JsonUtils.toJson(result));
        }

        public static void main(String[] args) {
            try {
                ref2video26();
            } catch (ApiException | NoApiKeyException | InputRequiredException e) {
                System.out.println(e.getMessage());
            }
            System.exit(0);
        }
    }
    ```
  </Tab>

  <Tab title="Asynchronous">
    Asynchronous calls return a task ID immediately. You must poll or wait for the task to complete.

    ##### Request example <span id="r2v839a7h5jr02" /> <span id="r2v839a6secrq2" />

    ```java expandable
    // 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.List;

    public class Ref2Video26Async {

        static {
            // Singapore region URL. Use the URL for your region.
            Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        }

        // If DASHSCOPE_API_KEY is not set, replace the following line with: apiKey="sk-xxx"
        // API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/model-studio/get-api-key
        public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

        public static void asyncRef2video26() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
            VideoSynthesis vs = new VideoSynthesis();
            List<String> referenceUrls = new ArrayList<>();
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
            referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");

            VideoSynthesisParam param =
                    VideoSynthesisParam.builder()
                            .apiKey(apiKey)
                            .model("wan2.6-r2v-flash")
                            .prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
                            .referenceUrls(referenceUrls)
                            .shotType(VideoSynthesis.ShotType.MULTI)
                            .audio(Boolean.TRUE)
                            .size("1280*720")
                            .duration(10)
                            .watermark(Boolean.TRUE)
                            .build();
            // Submit an 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 {
                asyncRef2video26();
            } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
                System.out.println(e.getMessage());
            }
            System.exit(0);
        }
    }
    ```
  </Tab>
</Tabs>

## Error codes <span id="OajFO" /> <span id="44b0b5c515ys8" />

If the model call fails and returns an error message, see [Error codes](/help/en/model-studio/error-code) for resolution.