# Wan2.7 - text-to-video API reference

> The Wan text-to-video model generates smooth videos from text prompts .

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

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

Match the region for your model, endpoint URL, and API key. Cross-region calls fail.

- [Select a model](https://modelstudio.console.alibabacloud.com/model/market): Go to Model Gallery to select a model and verify its region.
- <strong>Select a URL</strong>: Use the endpoint URL for the corresponding region. HTTP and HTTPS are both supported.
- <strong>Configure an API key</strong>: Select a region, [get an API key](/help/en/model-studio/get-api-key), and [configure it in environment variables](/help/en/model-studio/get-api-key).
- <strong>Install the SDK</strong>: To call the API through an SDK, [install the DashScope SDK](/help/en/model-studio/install-sdk).

<Note>
  Sample code in this topic uses the <strong>Singapore</strong> region.
</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 (wan2.7) <span id="a64683584eh3t" /> <span id="140640eec4f9y" />

<Tip>
  This interface uses the <strong>new protocol</strong> and supports only <strong>wan2.7</strong>.
</Tip>

Text-to-video tasks take 1–5 minutes. The API uses asynchronous invocation: <strong>Create a task → Poll for the result</strong>.

#### Step 1: Create a task <span id="92226a3dffgfc" /> <span id="cc739a3f13hrc" />

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

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

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

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

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

<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 style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

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

      <td rowSpan={9}>
        <Tabs>
          <Tab title="Multi-shot narrative">
            Control shot structure with natural language in the `prompt`. The `shot_type` parameter has no effect.

            - Single shot: Input "Generate a single-shot video".
            - Multi-shot: Input "Generate a multi-shot video" or describe shots with timestamps (e.g., "Shot 1 \[0–3 seconds] wide shot: Rainy New York street at night").
            - Default: If unspecified, the model interprets the `prompt` content.

            ```bash
            curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
                    -H 'X-DashScope-Async: enable' \
                    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
                    -H 'Content-Type: application/json' \
                    -d '{
                    "model": "wan2.7-t2v-2026-06-12",
                    "input": {
                        "prompt": "A tense detective story with cinematic storytelling. Shot 1 [0–3 seconds] wide shot: Rainy New York street at night, neon lights flicker, a detective in a black trench coat walks briskly. Shot 2 [3–6 seconds] medium shot: The detective enters an old building, rain wets his coat, the door closes slowly behind him. Shot 3 [6–9 seconds] close-up: The detective's focused eyes, distant sirens sound, he frowns slightly. Shot 4 [9–12 seconds] medium shot: The detective moves carefully down a dim hallway, his flashlight illuminating the way. Shot 5 [12–15 seconds] close-up: The detective discovers a key clue, his face shows sudden realization."
                    },
                    "parameters": {
                        "resolution": "720P",
                        "ratio": "16:9",
                        "prompt_extend": true,
                        "watermark": true,
                        "duration": 15
                    }
                }'
            ```
          </Tab>

          <Tab title="Provide an audio file">
            Specify a custom audio file URL in the `input.audio_url` parameter.

            ```bash
            curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
                    -H 'X-DashScope-Async: enable' \
                    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
                    -H 'Content-Type: application/json' \
                    -d '{
                    "model": "wan2.7-t2v-2026-06-12",
                    "input": {
                        "prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
                        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3"
                    },
                    "parameters": {
                        "resolution": "1080P",
                        "ratio": "16:9",
                        "prompt_extend": true,
                        "duration": 10
                    }
                }'
            ```
          </Tab>

          <Tab title="Automatic dubbing">
            Without `input.audio_url`, the model generates background music or sound effects that match the video content.

            ```bash
            curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
                    -H 'X-DashScope-Async: enable' \
                    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
                    -H 'Content-Type: application/json' \
                    -d '{
                    "model": "wan2.7-t2v-2026-06-12",
                    "input": {
                        "prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'."
                    },
                    "parameters": {
                        "resolution": "720P",
                        "ratio": "16:9",
                        "prompt_extend": true,
                        "duration": 10
                    }
                }'
            ```
          </Tab>

          <Tab title="Use a negative prompt">
            Use negative\_prompt to exclude the "flower" element and prevent it from appearing in the video.

            ```bash
            curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
                    -H 'X-DashScope-Async: enable' \
                    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
                    -H 'Content-Type: application/json' \
                    -d '{
                    "model": "wan2.7-t2v-2026-06-12",
                    "input": {
                        "prompt": "A kitten running in the moonlight",
                        "negative_prompt": "flower"
                    },
                    "parameters": {
                        "resolution": "720P",
                        "ratio": "16:9"
                    }
                }'
            ```
          </Tab>

          <Tab title="dashscope CLI">
            Call via the dashscope command line.

            ```bash
            export DASHSCOPE_API_KEY="your-api-key"
            # Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
            export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
            dashscope video-synthesis create -m wan2.7-t2v -p "a kitten running"
            ```

            <Tip>The SDK Expert interactive assistant can accomplish the same development and troubleshooting via natural language, see [DashScope SDK Expert](/help/en/model-studio/dashscope-sdk-expert).</Tip>

            For the complete region table, see [Base URL overview](/help/en/model-studio/base-url).
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>
        ##### Headers <span id="1a653493dcvcz" />
      </td>
    </tr>

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

        The content type of the request. Must be `application/json`.
      </td>
    </tr>

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

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
      </td>
    </tr>

    <tr>
      <td>
        <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>
      </td>
    </tr>

    <tr>
      <td>
        ##### Request body <span id="4ea8b46965895" />
      </td>
    </tr>

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

        Model name. For models and pricing, see [Model pricing](/help/en/model-studio/models).

        Example: wan2.7-t2v, wan2.7-t2v-2026-06-12.
      </td>
    </tr>

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

        Input data, including the prompt.

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

          Text prompt describing the video content and visual style.

          Supports Chinese and English. Each character or letter counts as one. Text beyond the limit is auto-truncated. Maximum length by model:

          - wan2.7-t2v, wan2.7-t2v-2026-06-12: Up to 5,000 characters.

          Example: A kitten running in the moonlight.

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

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

          Elements to exclude from the generated video.

          Supports Chinese and English. Maximum 500 characters; longer text is auto-truncated.

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

          <strong>audio\_url</strong> `string` (Optional)

          URL of the audio file for video generation.

          Supported formats:

          1. Public URL:

             - HTTP and HTTPS protocols.
             - Example: <a href="https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3">[https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3](https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3)</a>.

          Audio limits:

          - Format: WAV, MP3.
          - Duration: 2–30 seconds.
          - File size: Up to 15 MB.
          - Duration handling: If the audio exceeds the `duration` value (for example, 5 seconds), only the first 5 seconds are used. If the audio is shorter than the video, the remaining video is silent. For example, 3-second audio with a 5-second video produces 3 seconds of audio followed by 2 seconds of silence.
        </Accordion>
      </td>
    </tr>

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

        Video generation parameters: resolution, prompt rewriting, and watermark.

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

          <Tip>
            Resolution affects cost. Check [Model pricing](/help/en/model-studio/models) before calling.
          </Tip>

          Resolution tier of the generated video. Controls the output clarity (total pixel count).

          - wan2.7-t2v, wan2.7-t2v-2026-06-12: Valid values: 720P, 1080P. Default: `1080P`.

          <strong>ratio</strong> `string` (Optional)

          Aspect ratio of the output video.

          - `16:9` (default)
          - `9:16`
          - `1:1`
          - `4:3`
          - `3:4`

          Output resolutions (width\*height) by aspect ratio:

          <table style={{ display: "table", tableLayout: "fixed", width: "100%" }}><colgroup><col style={{ width: "33.3%" }} /><col style={{ width: "33.3%" }} /><col style={{ width: "33.4%" }} /></colgroup><tbody><tr><td><p>Resolution tier</p></td><td><p>Aspect ratio</p></td><td><p>Output video resolution (width\*height)</p></td></tr><tr><td rowSpan={5}><p>720P</p></td><td><p>16:9</p></td><td><p>1280\*720</p></td></tr><tr><td><p>9:16</p></td><td><p>720\*1280</p></td></tr><tr><td><p>1:1</p></td><td><p>960\*960</p></td></tr><tr><td><p>4:3</p></td><td><p>1104\*832</p></td></tr><tr><td><p>3:4</p></td><td><p>832\*1104</p></td></tr><tr><td rowSpan={5}><p>1080P</p></td><td><p>16:9</p></td><td><p>1920\*1080</p></td></tr><tr><td><p>9:16</p></td><td><p>1080\*1920</p></td></tr><tr><td><p>1:1</p></td><td><p>1440\*1440</p></td></tr><tr><td><p>4:3</p></td><td><p>1648\*1248</p></td></tr><tr><td><p>3:4</p></td><td><p>1248\*1648</p></td></tr></tbody></table>

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

          <Tip>
            Duration affects cost. Billing is per second. Check [Model pricing](/help/en/model-studio/model-pricing) before calling.
          </Tip>

          Duration of the output video, in seconds.

          - wan2.7-t2v, wan2.7-t2v-2026-06-12: An integer from 2 to 15. Default: 5.

          <strong>prompt\_extend</strong>`boolean` (Optional)

          Enables prompt rewriting. When enabled, an LLM rewrites the input prompt to improve generation quality. Best for short prompts but adds latency.

          - `true` (default)
          - `false`

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

          Adds a watermark in the lower-right corner with the text "AI Generated".

          - `false` (default)
          - `true`

          <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>
    </tr>
  </tbody>
</table>

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.54%" }} />

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

  <tbody>
    <tr>
      <td>
        #### Response parameters <span id="82c91c55bajs9" /> <span id="ed1e4de0f271q" />
      </td>

      <td rowSpan={5}>
        <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>

    <tr>
      <td>
        <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>
      </td>
    </tr>

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

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

    <tr>
      <td>
        <strong>code</strong> `string`

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

    <tr>
      <td>
        <strong>message</strong> `string`

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

#### Step 2: Query the result <span id="717bb080fb5ei" /> <span id="848c0461f9xj1" />

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

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

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

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

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

<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 style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

  <tbody>
    <tr>
      <td>
        #### Request parameters <span id="9d845a49dby6o" /> <span id="2982af2658yrv" />
      </td>

      <td rowSpan={5}>
        <Tabs>
          <Tab title="Query 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>

    <tr>
      <td>
        ##### Headers <span id="3e1bc6b9191mw" />
      </td>
    </tr>

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

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
      </td>
    </tr>

    <tr>
      <td>
        ##### Path parameters <span id="5670618eafm66" />
      </td>
    </tr>

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

        The ID of the task.
      </td>
    </tr>
  </tbody>
</table>

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

  <tbody>
    <tr>
      <td>
        #### Response parameters <span id="899988bcbfllm" /> <span id="dd6e5b8c71o7r" />
      </td>

      <td rowSpan={4}>
        <Tabs>
          <Tab title="Task executed successfully">
            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-09-29 14:18:52.331",
                    "scheduled_time": "2025-09-29 14:18:59.290",
                    "end_time": "2025-09-29 14:23:39.407",
                    "orig_prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
                    "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
                },
                "usage": {
                    "duration": 10,
                    "input_video_duration": 0,
                    "output_video_duration": 10,
                    "video_count": 1,
                    "ratio": "16:9",
                    "SR": 720
                }
            }
            ```
          </Tab>

          <Tab title="Task execution 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 does not match xxxxxx"
                }
            }
            ```
          </Tab>

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

    <tr>
      <td>
        <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>

          <strong>State transitions during polling:</strong>

          - PENDING → RUNNING → SUCCEEDED or FAILED.
          - The initial query status is usually PENDING or RUNNING.
          - When the status changes to SUCCEEDED, the response contains the generated video URL.
          - If the status is FAILED, check the error message and retry the task.

          <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>
      </td>
    </tr>

    <tr>
      <td>
        <strong>usage</strong> `object`

        Output statistics. Returned only for successful tasks.

        <Accordion title="Properties" defaultOpen>
          <strong>duration</strong> `float`

          Total video duration, used for billing.

          Equal to `output_video_duration`.

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

          Fixed value: 0.

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

          Output video duration in seconds. Matches the `input.duration` value.

          <strong>SR</strong> `integer`

          Resolution tier of the output video. Example: 720.

          <strong>ratio</strong> `string`

          Aspect ratio of the output video. Example: 16:9.

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

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

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

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

## HTTP (wan2.6 and earlier) <span id="42703589880ts" /> <span id="7c782df20fkq8" />

<Tip>
  This interface uses the <strong>legacy protocol</strong> and supports <strong>wan2.6 and earlier (wan2.5/wan2.2/wan2.1)</strong>.
</Tip>

Text-to-video tasks take 1–5 minutes, so the API uses asynchronous invocation: <strong>Create a task → Poll for the result</strong>.

#### 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`
  </Tab>

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

  <Tab title="Beijing">
    `POST https://{WorkspaceId}.cn-beijing.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`
  </Tab>
</Tabs>

Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/obtain-the-app-id-and-workspace-id#d3eb3cd37b7fu).

<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 style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

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

      <td rowSpan={9}>
        <Tabs>
          <Tab title="Multi-shot narrative">
            - To create a multi-shot narrative, set `shot_type` to `"multi"`.
            - Set `prompt_extend` to `true` to enable prompt rewriting for storyboard optimization.

            ```bash
            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-t2v",
                    "input": {
                        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \".",
                        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3"
                    },
                    "parameters": {
                        "size": "1280*720",
                        "prompt_extend": true,
                        "duration": 10,
                        "shot_type":"multi"
                    }
                }'
            ```
          </Tab>

          <Tab title="Pass an audio file">
            Supported models: wan2.6 and wan2.5 series.

            Set the `input.audio_url` parameter to a custom audio file URL.

            ```bash
            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.5-t2v-preview",
                    "input": {
                        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \".",
                        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3"
                    },
                    "parameters": {
                        "size": "832*480",
                        "prompt_extend": true,
                        "duration": 10
                    }
                }'
            ```
          </Tab>

          <Tab title="Automatic dubbing">
            Supported models: wan2.6 and wan2.5 series.

            Without the `input.audio_url` parameter, the model generates background music or sound effects that match the video content.

            ```bash
            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.5-t2v-preview",
                    "input": {
                        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \""
                    },
                    "parameters": {
                        "size": "832*480",
                        "prompt_extend": true,
                        "duration": 10
                    }
                }'
            ```
          </Tab>

          <Tab title="Generate a silent video">
            Only wan2.2 and wan2.1 series models support silent video generation. These models produce silent videos by default without additional configuration.

            > The wan2.6 and wan2.5 series models generate videos with audio by default.

            ```bash
            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.2-t2v-plus",
                    "input": {
                        "prompt": "Low contrast. In a retro 1970s-style subway station, a street musician plays amidst dim colors and rough textures. He wears an old-fashioned jacket and holds a guitar, playing with concentration. Commuters hurry past, and a small crowd gradually gathers to listen. The camera slowly pans to the right, capturing a scene where the sound of the instrument mixes with the city's noise, with old-fashioned subway signs and mottled walls in the background."
                    },
                    "parameters": {
                        "size": "832*480",
                        "prompt_extend": true
                    }
                }'
            ```
          </Tab>

          <Tab title="Use a negative prompt">
            Supported models: All models.

            Use negative\_prompt to exclude specific elements (such as "flowers") from the generated video.

            ```bash
            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.2-t2v-plus",
                    "input": {
                        "prompt": "A kitten running in the moonlight",
                        "negative_prompt": "flowers"
                    },
                    "parameters": {
                        "size": "832*480"
                    }
                }'
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>
        ##### Request headers <span id="79473e45c592d" />
      </td>
    </tr>

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

        The content type of the request. Must be `application/json`.
      </td>
    </tr>

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

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
      </td>
    </tr>

    <tr>
      <td>
        <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>
      </td>
    </tr>

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

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

        Model name. For models and pricing, see [Model pricing](/help/en/model-studio/models).

        Example: wan2.6-t2v.
      </td>
    </tr>

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

        Input data, including the prompt.

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

          Text prompt describing the video content and visual style.

          Supports Chinese and English. Each character or letter counts as one. Text beyond the limit is auto-truncated. Maximum length by model:

          - wan2.6 and wan2.5 series models: Up to 1,500 characters.
          - wan2.2 and wan2.1 series models: Up to 800 characters.

          Example: A kitten running in the moonlight.

          For tips, see [Text-to-Video/Image-to-Video Prompt Guide](/help/en/model-studio/text-to-video-prompt).

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

          Elements to exclude from the generated video.

          Supports Chinese and English. Maximum 500 characters; longer text is auto-truncated.

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

          <strong>audio\_url</strong> `string` (Optional)

          <strong>Supported models: wan2.6 and wan2.5 series.</strong>

          URL of the audio file for video generation.

          Supported formats:

          1. Public URL:

             - HTTP and HTTPS protocols.
             - Example: <a href="https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3">[https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3](https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3)</a>.

          Audio limits:

          - Format: WAV, MP3.
          - Duration: 3 s to 30 s.
          - File size: Up to 15 MB.
          - Duration handling: If the audio exceeds the `duration` value (for example, 5 s), only the first 5 s are used. If the audio is shorter than the video, the remaining video is silent. For example, 3 s audio with a 5 s video produces 3 s of audio followed by 2 s of silence.
        </Accordion>
      </td>
    </tr>

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

        Video generation parameters: resolution, prompt rewriting, and watermark.

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

          <Tip>
            - The `size` parameter affects cost: Cost = Unit price (resolution-based) x Duration (seconds). For the same model: 1080p > 720p > 480p. Check [model pricing](/help/en/model-studio/models).
            - Set `size` to a specific resolution (such as `1280*720`), not an aspect ratio (1:1) or tier label (480p).
          </Tip>

          Output video resolution in `width*height` format. Defaults and valid values depend on the model:

          - <strong>wan2.6-t2v</strong>: The default value is `1920*1080` (1080p). Valid resolutions: all in the 720p and 1080p tiers.
          - <strong>wan2.6-t2v-us</strong>: The default value is `1920*1080` (1080p). Valid resolutions: all in the 720p and 1080p tiers.
          - <strong>wan2.5-t2v-preview</strong>: The default value is `1920*1080` (1080p). Valid resolutions: all in the 480p, 720p, and 1080p tiers.
          - <strong>wan2.2-t2v-plus</strong>: The default value is `1920*1080` (1080p). Valid resolutions: all in the 480p and 1080p tiers.
          - <strong>wan2.1-t2v-turbo</strong>: The default value is `1280*720` (720p). Valid resolutions: all in the 480p and 720p tiers.
          - <strong>wan2.1-t2v-plus</strong>: The default value is `1280*720` (720p). Valid resolutions: all those in the 720p tier.

          480p tier resolutions and aspect ratios:

          - `832*480`: 16:9.
          - `480*832`: 9:16.
          - `624*624`: 1:1.

          720p tier 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 resolutions and 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 affects cost: Cost = Unit price (resolution-based) x Duration (seconds). Check [model pricing](/help/en/model-studio/model-pricing).
          </Tip>

          Output video duration in seconds. Valid values depend on the model:

          - wan2.6-t2v: An integer from 2 to 15. The default value is 5.
          - wan2.6-t2v-us: Valid values are 5 and 10. The default value is 5.
          - wan2.5-t2v-preview: Valid values are 5 and 10. The default value is 5.
          - wan2.2-t2v-plus: Fixed at 5 seconds and cannot be changed.
          - wan2.1-t2v-plus: Fixed at 5 seconds and cannot be changed.
          - wan2.1-t2v-turbo: Fixed at 5 seconds and cannot be changed.

          <strong>prompt\_extend</strong>`boolean` (Optional)

          Enables prompt rewriting. When enabled, an LLM rewrites the input prompt to improve quality. Best for short prompts but adds latency.

          - `true` (default)
          - `false`

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

          <strong>Supported models: wan2.6 models.</strong>

          Shot structure for the output video: one continuous shot or multiple shots with transitions.

          Valid values:

          - `single` (default)
          - `multi`

          This parameter takes effect only when `"prompt_extend": true` is set.

          Priority: `shot_type` overrides the prompt. Setting `shot_type` to `single` produces a single-shot video even if the prompt requests multi-shot.

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

          Adds a watermark in the lower-right corner with the text "AI Generated".

          - `false` (default)
          - `true`

          <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>
    </tr>
  </tbody>
</table>

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.54%" }} />

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

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

      <td rowSpan={5}>
        <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>

    <tr>
      <td>
        <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>
      </td>
    </tr>

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

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

    <tr>
      <td>
        <strong>code</strong> `string`

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

    <tr>
      <td>
        <strong>message</strong> `string`

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

#### Step 2: Query the 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}`
  </Tab>

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

  <Tab title="Beijing">
    `GET https://{WorkspaceId}.cn-beijing.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}`
  </Tab>
</Tabs>

Replace `{WorkspaceId}` with your actual [workspace ID](/help/en/model-studio/obtain-the-app-id-and-workspace-id#d3eb3cd37b7fu).

<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 style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

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

      <td rowSpan={5}>
        <Tabs>
          <Tab title="Query 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/obtain-the-app-id-and-workspace-id#d3eb3cd37b7fu).

            ```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>

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

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

        Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
      </td>
    </tr>

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

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

        The ID of the task.
      </td>
    </tr>
  </tbody>
</table>

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}>
  <colgroup>
    <col style={{ width: "53.88%" }} />

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

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

      <td rowSpan={4}>
        <Tabs>
          <Tab title="Task executed successfully">
            Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

            ```json
            {
                    "request_id": "abbf7aa3-9652-4785-a622-xxxxxx",
                    "output": {
                        "task_id": "38513c71-5190-48e1-9f3b-xxxxxx",
                        "task_status": "SUCCEEDED",
                        "submit_time": "2025-09-29 14:05:22.119",
                        "scheduled_time": "2025-09-29 14:05:28.278",
                        "end_time": "2025-09-29 14:10:00.437",
                        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them'.",
                        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
                    },
                    "usage": {
                        "duration": 10,
                        "size": "1280*720",
                        "input_video_duration": 0,
                        "output_video_duration": 10,
                        "video_count": 1,
                        "SR": 720
                    }
                }
            ```
          </Tab>

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

    <tr>
      <td>
        <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>

          <strong>State transitions during polling:</strong>

          - PENDING → RUNNING → SUCCEEDED or FAILED.
          - The initial query status is usually PENDING or RUNNING.
          - When the status changes to SUCCEEDED, the response contains the generated video URL.
          - If the status is FAILED, check the error message and retry the task.

          <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>actual\_prompt</strong> `string`

          When `prompt_extend=true`, the system rewrites the input prompt. This field contains the rewritten prompt used for generation.

          - Not returned when `prompt_extend=false`.
          - The wan2.6 model does not return this field, regardless of the `prompt_extend` value.

          <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>
      </td>
    </tr>

    <tr>
      <td>
        <strong>usage</strong> `object`

        Output statistics. Returned only for successful tasks.

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

          Returned only for wan2.5 and earlier (used for billing).

          Duration of the output video in seconds. Valid values: 5, 10.

          <strong>duration</strong> `float`

          Returned only for wan2.6 (used for billing).

          Total video duration. Formula: `duration=input_video_duration+output_video_duration`.

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

          Returned only for wan2.6. Fixed value: 0.

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

          Returned only for wan2.6.

          Output video duration in seconds. Matches the `input.duration` value.

          <strong>SR</strong> `integer`

          Returned only for wan2.6. Resolution tier of the output video. Example: 720.

          <strong>size</strong> `string`

          Returned only for wan2.6. Output resolution in "width×height" format. Example: 1920×1080.

          <strong>video\_ratio</strong> `string`

          Returned only for wan2.5 and earlier. Output resolution in "width×height" format. Example: 832×480.

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

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

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

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

## DashScope SDK <span id="db17b3098c2iv" /> <span id="41ca556e17lbx" />

SDK parameter names mostly match the [HTTP API](/help/en/model-studio/text-to-video-api-reference#42703589880ts), with structures following language-specific conventions.

Text-to-video tasks take 1–5 minutes. The SDK wraps the asynchronous HTTP call flow and supports both synchronous and asynchronous invocation.

> Actual processing time depends on queue depth and service load.

### Python SDK <span id="a3ad9a3b6d9if" /> <span id="cf97f2c7e50cg" />

<Tip>
  - The SDK supports wan2.6 and earlier. <strong>wan2.7 is not supported.</strong>
  - DashScope Python SDK version <strong>1.25.8</strong> or later is required.

    Older versions may return "url error, please check url!". To update, see [Install the SDK](/help/en/model-studio/install-sdk).
</Tip>

Set <strong>dashscope.base\_http\_api\_url</strong> to the region endpoint:

<Tabs>
  <Tab title="Beijing">
    `dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'`
  </Tab>

  <Tab title="Singapore">
    `dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'`
  </Tab>

  <Tab title="Virginia">
    `dashscope.base_http_api_url = 'https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1'`
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Synchronous invocation">
    ##### Request example <span id="3cd4969b00193" /> <span id="a86efc45d1joz" />

    ```python expandable
    from http import HTTPStatus
    from dashscope import VideoSynthesis
    import dashscope
    import os

    # URL for the Singapore region. URLs vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/text-to-video-api-reference.
    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    # If no environment variable is configured, replace with your Model Studio API key: api_key="sk-xxx".
    # API keys vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/get-api-key.
    api_key = os.getenv("DASHSCOPE_API_KEY")

    def sample_sync_call_t2v():
        # Call the sync API and return the result.
        print('Please wait...')
        rsp = VideoSynthesis.call(api_key=api_key,
                                  model='wan2.6-t2v',
                                  prompt="Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them.'",
                                  audio_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3',
                                  size='1280*720',
                                  duration=10,
                                  negative_prompt="",
                                  prompt_extend=True,
                                  watermark=False,
                                  seed=12345)
        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_t2v()
    ```

    ##### Response example <span id="0c0533477emwb" />

    > The video\_url expires after 24 hours. Download promptly.

    ```json
    {
        "status_code": 200,
        "request_id": "167f3beb-3dd0-47fe-a83c-xxxxxx",
        "code": null,
        "message": "",
        "output": {
            "task_id": "5b65411f-d946-4e29-859e-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-result-bj.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "submit_time": "2025-10-23 11:47:23.879",
            "scheduled_time": "2025-10-23 11:47:34.351",
            "end_time": "2025-10-23 11:52:35.323",
            "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '."
        },
        "usage": {
            "video_count": 1,
            "video_duration": 0,
            "video_ratio": "",
            "duration": 10,
            "size": "1280*720",
            "input_video_duration": 0,
            "output_video_duration": 10,
            "SR": 720
        }
    }
    ```
  </Tab>

  <Tab title="Asynchronous invocation">
    ##### Request example <span id="b994ca9918t7e" /> <span id="abd6f34917wlj" />

    ```python expandable
    from http import HTTPStatus
    from dashscope import VideoSynthesis
    import dashscope
    import os

    # This is the Singapore region URL. URLs vary by region. For more information, see: https://www.alibabacloud.com/help/model-studio/text-to-video-api-reference
    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    # If an environment variable is not configured, replace this with your Model Studio API key: api_key="sk-xxx"
    # API keys vary by region. For more information, see: https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key = os.getenv("DASHSCOPE_API_KEY")

    def sample_async_call_t2v():
        # Call the asynchronous API and return the task information.
        # Use the task ID to check the status.
        rsp = VideoSynthesis.async_call(api_key=api_key,
                                        model='wan2.6-t2v',
                                        prompt="Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.",
                                        audio_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3',
                                        size='1280*720',
                                        duration=10,
                                        negative_prompt="",
                                        prompt_extend=True,
                                        watermark=False,
                                        seed=12345)
        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))

        # Retrieve the task information, including the task status.
        status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
        if status.status_code == HTTPStatus.OK:
            print(status.output.task_status)  # Check the task status.
        else:
            print('Failed. Status code: %s, code: %s, message: %s' %
                  (status.status_code, status.code, status.message))

        # Wait for the task to complete. This method calls fetch at intervals and checks if the task is in a finished state.
        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_t2v()
    ```

    ##### Response example <span id="ae28dc8f72g6i" />

    1. Task creation response example

    ```json
    {
    	"status_code": 200,
    	"request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
    	"code": "",
    	"message": "",
    	"output": {
    		"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
    		"task_status": "PENDING",
    		"video_url": ""
    	},
    	"usage": null
    }
    ```

    2. Task query response example

       > The video\_url expires after 24 hours. Download promptly.

    ```
    {
        "status_code": 200,
        "request_id": "167f3beb-3dd0-47fe-a83c-xxxxxx",
        "code": null,
        "message": "",
        "output": {
            "task_id": "5b65411f-d946-4e29-859e-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-result-bj.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "submit_time": "2025-10-23 11:47:23.879",
            "scheduled_time": "2025-10-23 11:47:34.351",
            "end_time": "2025-10-23 11:52:35.323",
            "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '."
        },
        "usage": {
            "video_count": 1,
            "video_duration": 0,
            "video_ratio": "",
            "duration": 10,
            "size": "1280*720",
            "input_video_duration": 0,
            "output_video_duration": 10,
            "SR": 720
        }
    }
    ```
  </Tab>
</Tabs>

### Java SDK <span id="589b80853e6rn" /> <span id="0910550f7e6es" />

<Tip>
  - The SDK supports wan2.6 and earlier. <strong>wan2.7 is not supported.</strong>
  - DashScope Java SDK version <strong>2.22.6</strong> or later is required.

    Older versions may return "url error, please check url!". To update, see [Install the SDK](/help/en/model-studio/install-sdk).
</Tip>

Set <strong>Constants.baseHttpApiUrl</strong> to the region endpoint:

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

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

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

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

<Tabs>
  <Tab title="Synchronous invocation">
    ##### Request example <span id="3e3609efb9rhl" /> <span id="f6696dc876fg2" />

    ```java expandable
    // Copyright (c) Alibaba, Inc. and its affiliates.

    // dashscope SDK version 2.18.2 or later
    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.HashMap;
    import java.util.Map;

    public class Text2Video {

        static {
            // Singapore region URL. URLs vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/text-to-video-api-reference.
            Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        }

        // If no environment variable is configured, replace the value with your Model Studio API key: apiKey = "sk-xxx".
        // API keys vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/get-api-key.
        public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

        public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
            VideoSynthesis vs = new VideoSynthesis();
            Map<String, Object> parameters = new HashMap<>();
            parameters.put("prompt_extend", true);
            parameters.put("watermark", false);
            parameters.put("seed", 12345);

            VideoSynthesisParam param =
                    VideoSynthesisParam.builder()
                            .apiKey(apiKey)
                            .model("wan2.6-t2v")
                            .prompt("Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them'.")
                            .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3")
                            .negativePrompt("")
                            .size("1280*720")
                            .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 {
                text2Video();
            } catch (ApiException | NoApiKeyException | InputRequiredException e) {
                System.out.println(e.getMessage());
            }
            System.exit(0);
        }
    }
    ```

    ##### Response example <span id="dfe6c9cc786iy" />

    > The video\_url expires after 24 hours. Download promptly.

    ```json
    {
        "request_id": "c1209113-8437-424f-a386-xxxxxx",
        "output": {
            "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '",
            "submit_time": "2026-01-22 23:13:40.553",
            "scheduled_time": "2026-01-22 23:13:49.415",
            "end_time": "2026-01-22 23:17:56.380"
        },
        "usage": {
            "video_count": 1,
            "duration": 10.0,
            "size": "1280*720",
            "input_video_duration": 0.0,
            "output_video_duration": 10.0,
            "SR": "720"
        },
        "status_code": 200,
        "code": "",
        "message": ""
    }
    ```
  </Tab>

  <Tab title="Asynchronous invocation">
    ##### Request example <span id="2fc30f223b9py" /> <span id="3036efddf7ymv" />

    ```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.HashMap;
    import java.util.Map;

    public class Text2Video {
        static {
            // The URL for the Singapore region. URLs vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/text-to-video-api-reference
            Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        }

         // If an environment variable is not set, replace the placeholder with your Model Studio API key, for example: apiKey="sk-xxx"
        // API keys vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/get-api-key
        public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

        public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
            VideoSynthesis vs = new VideoSynthesis();
            Map<String, Object> parameters = new HashMap<>();
            parameters.put("prompt_extend", true);
            parameters.put("watermark", false);
            parameters.put("seed", 12345);

            VideoSynthesisParam param =
                    VideoSynthesisParam.builder()
                            .apiKey(apiKey)
                            .model("wan2.6-t2v")
                            .prompt("Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.")
                            .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3")
                            .negativePrompt("")
                            .size("1280*720")
                            .duration(10)
                            .parameters(parameters)
                            .build();

            // Make an asynchronous call.
            VideoSynthesisResult task = vs.asyncCall(param);
            System.out.println(JsonUtils.toJson(task));
            System.out.println("please wait...");

            // Retrieve the result.
            VideoSynthesisResult result = vs.wait(task, apiKey);
            System.out.println(JsonUtils.toJson(result));
        }

         // Retrieve the task list.
        public static void listTask() throws ApiException, NoApiKeyException {
            VideoSynthesis is = new VideoSynthesis();
            AsyncTaskListParam param = AsyncTaskListParam.builder().build();
            param.setApiKey(apiKey);
            VideoSynthesisListResult result = is.list(param);
            System.out.println(result);
        }

        // Retrieve the result of a single task.
        public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
            VideoSynthesis is = new VideoSynthesis();
            // If you set the DASHSCOPE_API_KEY environment variable, you can set apiKey to null.
            VideoSynthesisResult result = is.fetch(taskId, apiKey);
            System.out.println(result.getOutput());
            System.out.println(result.getUsage());
        }

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

    ##### Response example <span id="38e1e3c7303rm" />

    1. Task creation response example.

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

    2. Task query response example

       > The video\_url expires after 24 hours. Download promptly.

    ```json
    {
        "request_id": "c1209113-8437-424f-a386-xxxxxx",
        "output": {
            "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '",
            "submit_time": "2026-01-22 23:13:40.553",
            "scheduled_time": "2026-01-22 23:13:49.415",
            "end_time": "2026-01-22 23:17:56.380"
        },
        "usage": {
            "video_count": 1,
            "duration": 10.0,
            "size": "1280*720",
            "input_video_duration": 0.0,
            "output_video_duration": 10.0,
            "SR": "720"
        },
        "status_code": 200,
        "code": "",
        "message": ""
    }
    ```
  </Tab>
</Tabs>

## Limitations <span id="63a009e43a1iy" /> <span id="71ea6da9ddy3c" />

- <strong>Data retention</strong>: The task ID (`task_id`) and video URL (`video_url`) expire after 24 hours. After expiry, they cannot be queried or downloaded.
- <strong>Content moderation</strong>: Input and output undergo content moderation. Prohibited content triggers "IPInfringementSuspect" or "DataInspectionFailed" errors. See [Error codes](/help/en/model-studio/error-code).

## Error codes <span id="OajFO" /> <span id="3e1e579599soq" />

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

## FAQ <span id="c928ee689aw6l" /> <span id="506e4ba422lni" />

#### Q: What code changes are needed to upgrade from wan2.6 to wan2.7? <span id="cd79eb5127f4j" /> <span id="96508c4c3crmw" />

A: Two changes are required:

- <strong>Resolution control</strong>: wan2.7 replaces the `size` field. Instead, it uses a combination of `resolution` (resolution tier) and `ratio` (aspect ratio) to define output resolution. Earlier models used the `size` field.
- <strong>Shot type removal</strong>: wan2.7 drops the `shot_type` field. Describe shot structure directly in the prompt instead.

#### Q: How do I convert a temporary video link to a permanent one? <span id="99f5bae3c2y7a" /> <span id="f643ac0b57ecc" />

A: Direct conversion is not possible. Download the video from the URL, then upload it to persistent storage (such as Alibaba Cloud OSS) to generate a permanent link.

<Accordion title="Example code: Download a video to a local device">
  ```python
  import requests

  def download_and_save_video(video_url, save_path):
      try:
          response = requests.get(video_url, stream=True, timeout=300)
          response.raise_for_status()
          with open(save_path, 'wb') as f:
              for chunk in response.iter_content(chunk_size=8192):
                  f.write(chunk)
          print(f"Video successfully downloaded to: {save_path}")
          # You can add logic to upload the video to permanent storage here
      except requests.exceptions.RequestException as e:
          print(f"Failed to download video: {e}")

  if __name__ == '__main__':
      video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
      save_path = "video.mp4"
      download_and_save_video(video_url, save_path)
  ```
</Accordion>

#### Q: Can the returned video link be played directly in a browser? <span id="bc74fbbfach4a" /> <span id="9f057e0f939gd" />

A: No. The link expires after 24 hours. Download the video, store it persistently, and use a permanent link for playback.