All Products
Search

This Product

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

    Document Center

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

    Last Updated:Dec 27, 2025

    The Wan text-to-video model generates smooth videos based on text prompts. It supports the following features:

    • Basic features: You can select the video duration (5, 10, or 15 seconds), specify the video resolution (480P, 720P, or 1080P), enable intelligent prompt rewriting, and add watermarks.

    • Audio features: Automatic dubbing or using a custom audio file for audio-visual synchronization. (Supported by wan2.5 and wan2.6)

    • Multi-shot narrative: Supports generating videos with multiple shots while maintaining subject consistency across shot changes. (Supported only by wan2.6)

    Quick links: Try it online (Singapore | Beijing) | Wan official website

    Note

    The features on the Wan official website may differ from those supported by the API. This document describes the actual capabilities of the API and is updated as new features are released.

    Model overview

    Input prompt

    Output video (wan2.6, multi-shot video)

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

    Prerequisites

    Before making a call, obtain an API key and set the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.

    Important

    The Beijing and Singapore regions have separate API keys and request endpoints. Do not use them interchangeably. Cross-region calls cause authentication failures or service errors.

    HTTP Call

    Because text-to-video tasks take a long time to complete (typically 1 to 5 minutes), the API uses asynchronous invocation. The process involves two core steps: Create a task -> Poll for the result. The steps are as follows:

    The time required depends on the number of queued tasks and the service execution status. Please be patient while you wait for the result.

    Step 1: Create a task to get a task ID

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

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

    Note

    • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Use polling to retrieve the result.

    Request parameters

    Multi-shot narrative

    Only the wan2.6-t2v model supports generating multi-shot videos.

    Enable this feature by setting "prompt_extend": true and "shot_type":"multi".

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-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"
    }
}'

    Automatic dubbing

    This feature is supported only by wan2.5 and later models.

    If you do not provide input.audio_url, the model automatically generates matching background music or sound effects based on the video content.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.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
    }
}'

    Use an audio file

    This feature is supported only by wan2.5 and later models.

    To specify background music or dubbing for the video, pass the URL of your custom audio file using the input.audio_url parameter.

    # Note: If you use a model in the China (Mainland) Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.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
    }
}'

    Generate a silent video

    wan2.2 and earlier models generate silent videos by default. No parameters need to be set.

    wan2.5 and later models generate videos with audio by default.
    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.2-t2v-plus",
    "input": {
        "prompt": "Low contrast, in a retro 70s-style subway station, a street musician plays amidst dim colors and rough textures. He wears an old-style jacket, holds a guitar, and plays with concentration. Commuters hurry past, and a small crowd gradually gathers to listen. The camera slowly moves to the right, capturing the scene where the sound of the instrument intertwines with the hustle and bustle, with old-fashioned subway signs and mottled walls in the background."
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true
    }
}'

    Use a negative prompt

    You can use the `negative_prompt` parameter to exclude elements, such as "flowers", from appearing in the video.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.2-t2v-plus",
    "input": {
        "prompt": "A kitten running in the moonlight",
        "negative_prompt": "flowers"
    },
    "parameters": {
        "size": "832*480"
    }
}'
    Headers

    Content-Type string (Required)

    The content type of the request. Set this parameter to application/json.

    Authorization string (Required)

    The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.

    X-DashScope-Async string (Required)

    The asynchronous processing configuration parameter. HTTP requests support only asynchronous processing. You must set this parameter to enable.

    Important

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

    Request body

    model string (Required)

    The model name. For a list of available models and their pricing, see Model pricing.

    Example: wan2.5-t2v-preview.

    input object (Required)

    The basic input information, such as the prompt.

    Properties

    prompt string (Required)

    The text prompt. The prompt describes the desired elements and visual features in the generated video.

    Chinese and English are supported. Each Chinese character or letter is counted as one character. Any text that exceeds the limit is automatically truncated. The length limit varies by model version:

    • wan2.6-t2v: up to 1,500 characters.

    • wan2.5-t2v-preview: up to 1,500 characters.

    • wan2.2 and earlier models: up to 800 characters.

    Example: A kitten running in the moonlight.

    For tips on using prompts, see Text-to-video/image-to-video prompt guide.

    negative_prompt string (Optional)

    The negative prompt. It describes content that you do not want to appear in the video. This can be used to constrain the video content.

    Chinese and English are supported. The length is limited to 500 characters. Any text that exceeds the limit is automatically truncated.

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

    audio_url string (Optional)

    Supported models: wan2.6-t2v, wan2.5-t2v-preview.

    The URL of the audio file. The model will use this audio to generate the video. For more information, see Set audio parameters.

    HTTP and HTTPS protocols are supported.

    Audio limits:

    • Format: wav or mp3.

    • Duration: 3s to 30s.

    • File size: up to 15 MB.

    • Handling of excess length: If the audio duration exceeds the duration value (5s or 10s), only the first 5 or 10 seconds are used, and the rest is discarded. If the audio is shorter than the video, the part of the video that extends beyond the audio's length is silent. For example, if the audio is 3 seconds long and the video is 5 seconds long, the first 3 seconds of the output video have sound, and the last 2 seconds are silent.

    Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp3.

    parameters object (Optional)

    The image editing parameters. For example, you can set the video resolution, enable intelligent prompt rewriting, or add a watermark.

    Properties

    size string (Optional)

    Important

    • The `size` parameter directly affects the cost. The cost is calculated as follows: Unit price (based on resolution) × Duration (seconds). For the same model, 1080P > 720P > 480P. Confirm the model pricing before you make a call.

    • The `size` parameter must be set to a specific value, such as 1280*720. You cannot set it to an aspect ratio, such as 1:1, or a resolution tier, such as 480P.

    Specifies the resolution of the generated video in width*height format. The default value and available enumeration values for this parameter depend on the `model` parameter, as described in the following list:

    • wan2.6-t2v: The default value is 1920*1080 (1080P). Optional resolutions: all resolutions corresponding to 720P and 1080P.

    • wan2.5-t2v-preview: The default value is 1920*1080 (1080P). Optional resolutions: all resolutions corresponding to 480P, 720P, and 1080P.

    • wan2.2-t2v-plus: The default value is 1920*1080 (1080P). Optional resolutions: all resolutions corresponding to 480P and 1080P.

    • wan2.1-t2v-turbo: The default value is 1280*720 (720P). Optional resolutions: all resolutions corresponding to 480P and 720P.

    • wan2.1-t2v-plus: The default value is 1280*720 (720P). Optional resolutions: all resolutions corresponding to 720P.

    480P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 832*480: 16:9.

    • 480*832: 9:16.

    • 624*624: 1:1.

    720P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 1280*720: 16:9.

    • 720*1280: 9:16.

    • 960*960: 1:1.

    • 1088*832: 4:3.

    • 832*1088: 3:4.

    1080P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 1920*1080: 16:9.

    • 1080*1920: 9:16.

    • 1440*1440: 1:1.

    • 1632*1248: 4:3.

    • 1248*1632: 3:4.

    duration integer (Optional)

    Important

    The `duration` parameter directly affects the cost. The cost is calculated as follows: Unit price (based on resolution) × Duration (in seconds). Before you make a call, confirm the model pricing.

    The duration of the generated video, in seconds. The value of this parameter depends on the `model` parameter:

    • wan2.6-t2v: Optional values are 5, 10, and 15. The default value is 5.

    • wan2.5-t2v-preview: Optional values are 5 and 10. The default value is 5.

    • wan2.2-t2v-plus: Fixed at 5 seconds and cannot be modified.

    • wan2.1-t2v-plus: Fixed at 5 seconds and cannot be modified.

    • wan2.1-t2v-turbo: Fixed at 5 seconds and cannot be modified.

    Example: 5.

    prompt_extend boolean (Optional)

    Specifies whether to enable prompt rewriting. If enabled, a large language model (LLM) rewrites the input prompt. This can significantly improve the generation quality for shorter prompts but increases the time required.

    • true (default)

    • false

    Example: true.

    shot_type string (Optional)

    Supported model: wan2.6-t2v.

    Specifies the shot type of the generated video, that is, whether the video consists of a single continuous shot or multiple switched shots.

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

    Parameter priority: shot_type > prompt. For example, if shot_type is set to "single", the model generates a single-shot video even if the prompt requests a multi-shot video.

    Optional values:

    • single: (default) Outputs a single-shot video.

    • multi: Outputs a multi-shot video.

    Example: single.

    Note

    Use this parameter to strictly control the narrative structure of the video, such as using a single shot for a product display or multiple shots for a short story.

    watermark boolean (Optional)

    Specifies whether to add a watermark. The watermark, which says "AI Generated", is placed in the lower-right corner of the video.

    • false: (Default) No watermark is added.

    • true: Adds a watermark.

    Example: false.

    seed integer (Optional)

    The random number seed. The value must be in the range of [0, 2147483647].

    If you do not specify this parameter, the system automatically generates a random seed. To improve the reproducibility of the results, you can set a fixed seed value.

    Note that because model generation is probabilistic, using the same seed does not guarantee that the results are identical every time.

    Example: 12345.

    Response parameters

    Successful response

    Save the task_id to query the task status and result.

    {
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

    Error response

    The task creation failed. For more information, see Error messages to resolve the issue.

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

    output object

    The task output information.

    Properties

    task_id string

    The task ID. The query is valid for 24 hours.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status cannot be determined.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    code string

    The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    message string

    The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    Step 2: Query the result by task ID

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

    China (Beijing): GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    Note

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

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

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

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

    Request parameters

    Query task result

    Replace 86ecf553-d340-4e21-xxxxxxxxx with the actual task ID.

    The API keys for the Singapore and Beijing regions are different. Create an API key.
    The following `base_url` is for the Singapore region. For models in the Beijing region, replace the `base_url` with `https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx`.
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

    Headers

    Authorization string (Required)

    The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.

    URL path parameters

    task_id string (Required)

    The task ID.

    Response parameters

    Successful task execution

    Video URLs are retained for only 24 hours and are automatically purged after this period. You must save the generated videos promptly.

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

    Failed task execution

    If a task fails, task_status is set to FAILED, and an error code and message are provided. For more information, see Error messages to resolve the issue.

    {
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

    Task query expired

    The task_id is valid for 24 hours. After this period, the query fails and the following error message is returned.

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

    output object

    The task output information.

    Properties

    task_id string (Required)

    The task ID.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status cannot be determined.

    submit_time string

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

    scheduled_time string

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

    end_time string

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

    video_url string

    The video URL. This parameter is returned only if task_status is SUCCEEDED.

    The link is valid for 24 hours. You can use this URL to download the video. The video is in MP4 format with H.264 encoding.

    orig_prompt string

    The original input prompt. This corresponds to the prompt request parameter.

    actual_prompt string

    When prompt_extend=true, the system automatically rewrites the input prompt. This field returns the optimized prompt that is used for generation.

    • If prompt_extend=false, this field is not returned.

    • Note: The wan2.6 model does not return this field, regardless of the value of prompt_extend.

    code string

    The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    message string

    The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    usage object

    Statistics for the output information. Only successful results are counted.

    Properties

    video_duration integer

    This parameter is returned only for wan2.5 and earlier models and is used for billing.

    The duration of the generated video in seconds. Possible values are 5 and 10.

    duration float

    This parameter is returned only for the wan2.6 model and is used for billing.

    Indicates the total video duration, where duration=input_video_duration+output_video_duration.

    input_video_duration integer

    This parameter is returned only for the wan2.6 model. The value is fixed at 0.

    output_video_duration integer

    This parameter is returned only for the wan2.6 model.

    The duration of the output video in seconds. Its value is the same as the value of input.duration.

    SR integer

    This parameter is returned only for the wan2.6 model. It indicates the resolution tier of the generated video. Example: 720.

    size string

    Returned only for the wan2.6 model. The resolution of the generated video. Format: "width*height". Example: 1920*1080.

    video_ratio string

    Returned only for wan2.5 and earlier models. The resolution of the generated video. Format: "width*height". Example: 832*480.

    video_count integer

    The number of generated videos. This value is fixed at 1.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    DashScope SDK calls

    The parameter naming in the SDK is mostly consistent with the HTTP API. The parameter structure is encapsulated based on the features of each programming language.

    Because text-to-video tasks take a long time to complete (typically 1 to 5 minutes), the SDK encapsulates the HTTP asynchronous invocation process at the underlying layer and supports both synchronous and asynchronous invocation methods.

    The time required depends on the number of queued tasks and the service execution status. Please be patient while you wait for the result.

    Python SDK calls

    Important

    • The wan2.6-t2v model does not support SDK calls.

    • Make sure that your DashScope Python SDK version is 1.25.2 or later before you run the following code.

      If your SDK version is too low, you may encounter errors such as 'url error, please check url!'. For more information, see Install SDK to update your SDK.

    Synchronous invocation

    Request example
    from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_t2v():
    # call sync api, will return the result
    print('please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model='wan2.5-t2v-preview',
                              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='832*480',
                              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
    The video_url is valid for 24 hours. You should download the video 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 '.",
        "actual_prompt": "Low-angle shot, medium close-up, warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, 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 crimson fur contrasting with the dimly lit room. Its tail rests lightly on the edge of the chair, and its fingers slowly turn yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. The fox slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera. Its mouth clearly moves 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": 10,
        "video_ratio": "832*480"
    }
}

    Asynchronous invocation

    Request example
    from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_t2v():
    # call async api, will return the task information
    # you can get task status with the returned task id.
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model='wan2.5-t2v-preview',
                                    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='832*480',
                                    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))
                           
    # get the task information include 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 the task complete, will call fetch interval, and check it's in finished status.
    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

    1. Response example for creating a task

    {
	"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. Response example for querying a task result

    The video_url is valid for 24 hours. You should download the video 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 '.",
        "actual_prompt": "Low-angle shot, medium close-up, warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, 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 crimson fur contrasting with the dimly lit room. Its tail rests lightly on the edge of the chair, and its fingers slowly turn yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. The fox slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera. Its mouth clearly moves 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": 10,
        "video_ratio": "832*480"
    }
}

    Java SDK

    Important

    • The wan2.6-t2v model does not support SDK calls.

    • Make sure that your DashScope Java SDK version is 2.22.2 or later before you run the following code.

      If the version is too low, you may encounter errors such as 'url error, please check url!'. For more information, see Install the SDK to update.

    Synchronous invocation

    Request example
    // Copyright (c) Alibaba, Inc. and its affiliates.

// dashscope sdk >= 2.18.2
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 {
    /**
     * Create a video compositing task and wait for the task to complete.
     */
    static {
     Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
     // If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
    }
    
    // If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/zh/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.5-t2v-preview")
                        .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("832*480")
                        .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
    The video_url is valid for 24 hours. You should download the video promptly.
    {
    "request_id": "4e9aab26-c50b-4ea7-b2c0-xxxxxx",
    "output": {
        "task_id": "9e0fc846-ee92-42ac-af42-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 10,
        "video_ratio": "832*480"
    }
}

    Asynchronous invocation

    Request example
    // 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 {
    /**
     * Create a video compositing task and wait for the task to complete.
     */
    static {
        // If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }

     // If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // The API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/zh/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.5-t2v-preview")
                        .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("832*480")
                        .duration(10)
                        .parameters(parameters)
                        .build();

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

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

     // Get 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);
    }

    // Get the result of a single task
    public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
        VideoSynthesis is = new VideoSynthesis();
        // If DASHSCOPE_API_KEY is set as an environment variable, apiKey can be 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

    1. Response example for creating a task.

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

    2. Response example for querying a task result

    The video_url is valid for 24 hours. You should download the video promptly.
    {
    "request_id": "4e9aab26-c50b-4ea7-b2c0-xxxxxx",
    "output": {
        "task_id": "9e0fc846-ee92-42ac-af42-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 10,
        "video_ratio": "832*480"
    }
}

    Limitations

    • Data validity: The task_id and video URL are retained for only 24 hours. After this period, they can no longer be queried or downloaded.

    • Audio support: wan2.5 and later versions generate videos with audio by default (supporting automatic dubbing or custom audio upload). wan2.2 and earlier versions generate only silent videos. If needed, you can use speech synthesis to generate audio.

    • Content Moderation: The input prompt and output video are subject to Content Moderation. Requests that contain non-compliant content will result in the "IPInfringementSuspect" or "DataInspectionFailed" error. For more information, see Error messages.

    • Network access configuration: The video link is stored in Object Storage Service (OSS). If your business system cannot access external OSS links because of security policies, you must add the following OSS domain names to the network access whitelist.

      # OSS domain name list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

    Key parameter descriptions

    Set audio parameters

    Supported models: wan2.6-t2v, wan2.5-t2v-preview.

    Audio settings: wan2.5 and later versions generate videos with audio by default. The audio behavior depends on whether you provide input.audio_url. Two modes are supported:

    1. Automatic dubbing: When you do not provide audio_url, the model automatically generates matching background audio or music based on the prompt and video content.

    2. Use custom audio: When you provide audio_url, the model uses your audio file to generate the video. The video content aligns with the audio (such as lip movements and rhythm).

    Billing and rate limiting

    • For the free quota and unit price, see Models.

    • For rate limits, see Wan series.

    • Billing description:

      • You are billed based on the duration in seconds of successfully generated videos. You are charged only when the query result API returns a task_status of SUCCEEDED and a video is successfully generated.

      • No fees are incurred for failed model calls or processing errors, and your free quota is not consumed.

    Error codes

    If a call fails, see Error messages for troubleshooting.

    FAQ

    Q: How do I view the number of model calls?

    A: One hour after the model call is complete, you can go to the Model Observation (Singapore) or Model Observation (Beijing) page to view metrics such as the number of calls and the success rate for the model. For more information, see How do I view model call records?

    Q: How do I convert a temporary video link to a permanent one?

    A: You cannot directly convert the link. The correct method is to have the backend service download the video file using the URL and then upload it to a permanent object storage service, such as OSS, to generate a new, permanent access link.

    Example code: Download video to a local path

    import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set timeout
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200
        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}")
        # Logic to upload to permanent storage can be added 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)

    Q: Can the returned video link be played directly in a browser?

    A: This is not recommended because the link expires after 24 hours. The recommended best practice is to have the backend download and save the video, and then use a permanent link for playback.