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:Nov 04, 2025

    Wan text-to-video generates a smooth video based on a text prompt. The model supports the following features:

    • Basic features: Select the video duration (5 or 10 seconds), specify the video resolution (480p, 720p, or 1080p), prompt rewriting, and watermarks.

    • Audio features: Automatically generate audio or use a custom audio file for audio-video synchronization. (Supported only by wan2.5)

    Quick start:Try Wan online on the official website

    Note

    The features on the Wan official website may differ from the capabilities supported by the API. This document describes the actual capabilities of the API and will be updated promptly when new features are released.

    Model overview

    Input example

    Output video (wan2.5)

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

    Input audio:

    Model

    Description

    Output video specifications

    wan2.5-t2v-preview Recommended

    Wan 2.5 preview (Video with audio).

    New audio feature: You can automatically generate audio or use a custom audio file.

    Resolution options: 480p, 720p, 1080p

    Video duration: 5 seconds, 10 seconds

    Fixed specifications: 24 fps, MP4 (H.264 encoding) 

    wan2.2-t2v-plus Recommended

    Wan 2.2 Professional Edition (Silent video).

    This model offers improved stability and a higher success rate, with a 50% increase in speed compared to the 2.1 model.

    Resolution options: 480p, 1080p

    Video duration: 5 seconds

    Fixed specifications: 30 fps, MP4 (H.264 encoding) 

    wanx2.1-t2v-turbo

    Wan 2.1 Turbo Edition (Silent video)

    Resolution options: 480p, 720p

    Video duration: 5 seconds

    Fixed specifications: 30 fps, MP4 (H.264 encoding) 

    wanx2.1-t2v-plus

    Wan 2.1 Professional Edition (Silent video)

    Resolution options: 720p

    Video duration: 5 seconds

    Fixed specifications: 30 fps, MP4 (H.264 encoding) 

    Important

    Before making a call, check the Model List and Pricing for each region.

    Preparations

    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

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

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

    Step 1: Create a task and get the task ID

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

    China (Beijing) region: 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

    Automatic audio generation

    This feature is supported only by the wan2.5-t2v-preview model. The model has automatic audio generation enabled by default, so no configuration is required. To explicitly declare this, you can set the parameters.audio parameter to true.

    # 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.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,
        "audio": true
    }
}'

    Use an audio file

    This feature is supported only by the wan2.5-t2v-preview model. Pass the audio link 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/en-US/20250929/stjqnq/fox.mp3"
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true,
        "duration": 10
    }
}'

    Generate a silent video

    The method for generating a silent video varies by model version:

    • For the wan2.5-t2v-preview model, you must explicitly set the parameters.audio parameter to false.

    • For wan2.2 and earlier models, silent videos are generated by default. No parameters need to be set. See the code block below.

    # 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 city's hustle and bustle, with old-style subway signs and mottled walls in the background."
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true
    }
}'

    Use a negative prompt

    Use the `negative_prompt` parameter to exclude elements, such as "flowers", and prevent them 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.1-t2v-plus",
    "input": {
        "prompt": "A kitten running in the moonlight",
        "negative_prompt": "flowers"
    },
    "parameters": {
        "size": "832*480"
    }
}'
    Request 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 name of the model. For a list of models and their prices, see Models and pricing.

    Example: wan2.5-t2v-preview.

    input object (Required)

    The basic input information, such as the prompt.

    Properties

    prompt string (Required)

    The text prompt. It describes the desired elements and visual characteristics of the generated video.

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

    • wan2.5-t2v-preview: Up to 2,000 characters.

    • wan2.2 and earlier: Up to 800 characters.

    Example: A kitten running in the moonlight.

    For more information about prompt usage techniques, 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. You can use this parameter to constrain the video content.

    Chinese and English are supported. The length is limited to 500 characters. Any excess characters are automatically truncated.

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

    audio_url string (Optional)

    Supported only by wan2.5-t2v-preview. The URL of the audio file. The model uses this audio to generate the video. For more information about usage, see Audio settings.

    HTTP and HTTPS protocols are supported.

    Audio limits:

    • Format: wav, mp3.

    • Duration: 3 to 30s.

    • File size: Up to 15 MB.

    • Handling of oversized files: If the audio duration exceeds the duration value (5 or 10 seconds), the audio is truncated to the first 5 or 10 seconds, and the rest is discarded. If the audio is shorter than the video, the parts of the video that extend beyond the audio's length are 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/en-US/20250923/hbiayh/marching-song.mp3.

    parameters object (Optional)

    The video generation parameters. You can set the video resolution, enable prompt rewriting, add watermarks, and more.

    Properties

    size string (Optional)

    Important

    • The size directly affects the cost. Cost = Unit price (based on resolution) × Duration (seconds). For the same model, the cost hierarchy is 1080p > 720p > 480p. Before making a call, confirm the model pricing.

    • The `size` must be set to a specific value, such as 1280×720, not an aspect ratio or quality level such as 1:1 or 480p.

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

    • 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 options: The optional video resolutions and their corresponding aspect ratios are:

    • 832×480: 16:9.

    • 480×832: 9:16.

    • 624×624: 1:1.

    720p options: 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 options: 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 directly affects the cost. Cost = Unit price (based on resolution) × Duration (seconds). Before making 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.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.

    watermark boolean (Optional)

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

    • false (default): Does not add a watermark.

    • true: Adds a watermark.

    Example: false.

    audio boolean (Optional)

    Supported only by wan2.5-t2v-preview. Specifies whether to add audio. The parameter priority is `audio_url` > `audio`. This parameter takes effect only when audio_url is empty.

    • true (default): Automatically adds audio to the video.

    • false: Does not add audio. Outputs a silent video.

    Example: true.

    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":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-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

    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 region: GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

    China (Beijing) region: 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 (In queue) → RUNNING (Processing) → SUCCEEDED (Successful) or FAILED (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 Alibaba Cloud OSS.

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

    Request parameters

    Query task result

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

    The API keys for the Singapore and Beijing regions are different. Obtain an API key.
    The following code provides the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

    Request 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

    Task succeeded

    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",
        "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_duration": 10,
        "video_ratio": "832*480",
        "video_count": 1
    }
}

    Task failed

    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

    submit_time string

    The time when the task was submitted. The format is YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. The format is YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. 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

    If prompt rewriting is enabled, this parameter returns the actual optimized prompt that is used. If this feature is disabled, this parameter is not returned.

    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 about the output information. Only successful results are included in the statistics.

    Properties

    video_duration integer

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

    video_ratio string

    The resolution of the generated video, specified by the `size` request parameter, in the `width×height` format. Example: 1920×1080.

    video_count integer

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

    request_id string

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

    DashScope SDK

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

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

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

    Python SDK

    Note

    Install the latest version of the DashScope Python SDK to avoid potential runtime errors: Install or upgrade the SDK.

    Synchronous call

    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 an 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. To get an API key, see: https://www.alibabacloud.com/help/en/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/en-US/20250929/stjqnq/fox.mp3',
                              size='832*480',
                              duration=10,
                              negative_prompt="",
                              # audio=True,
                              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 call

    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 an 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. To get an API key, see: https://www.alibabacloud.com/help/en/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/en-US/20250929/stjqnq/fox.mp3',
                                    size='832*480',
                                    duration=10,
                                    negative_prompt="",
                                    # audio=True,
                                    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(rsp)
    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(rsp)
    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

    Note

    Install the latest version of the DashScope Java SDK to avoid potential runtime errors: Install or upgrade the SDK.

    Synchronous call

    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 an 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. To get an API key, see: https://www.alibabacloud.com/help/en/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/en-US/20250929/stjqnq/fox.mp3")
                        .negativePrompt("")
                        .size("832*480")
                        .duration(10)
                        // .audio(true)
                        .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 call

    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 an 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. To get an API key, see: https://www.alibabacloud.com/help/en/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/en-US/20250929/stjqnq/fox.mp3")
                        .negativePrompt("")
                        .size("832*480")
                        .duration(10)
                        // .audio(true)
                        .parameters(parameters)
                        .build();

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

        // Get the result
        // The apiKey is already configured in the environment variable, so it can be set to null here.
        VideoSynthesisResult result = vs.wait(task, null);
        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();
        VideoSynthesisListResult result = is.list(param);
        System.out.println(result);
    }

    // Get a single task result
    public 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, null);
        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"
    }
}

    Limits

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

    • Audio support: The wan2.5 model supports videos with audio, which can be automatically generated or uploaded by the user. The wan2.2 and earlier versions output only silent videos. If needed, you can use speech synthesis to generate audio.

    • Content moderation: The input prompt and output video are both subject to content moderation. Requests that contain prohibited content result in an "IPInfringementSuspect" or "DataInspectionFailed" error. For more information, see Error messages.

    • Network access configuration: The video link is stored in Alibaba Cloud OSS. If your business system cannot access external OSS links due to security policies, you must add the following OSS domain names to the network access whitelist.

      # List of OSS domain names
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

    Audio settings

    Supported model: wan2.5-t2v-preview.

    Audio settings: You can control the audio behavior using a combination of the input.audio_url and parameters.audio parameters. The parameter priority is audio_url > audio. Three modes are supported:

    1. Generate a silent video

      1. Parameter settings: Do not pass `audio_url`, and set `audio` to `false`.

      2. Scenario: This mode is for purely visual content where you plan to add audio or music later.

    2. Automatically generate audio

      1. Parameter settings: Do not pass `audio_url`, and set `audio` to `true`.

      2. Effect description: The model automatically generates matching background audio or music based on the prompt and the video content.

    3. Use custom audio

      1. Parameter settings: Pass `audio_url`. The `audio` parameter is ignored.

      2. Effect description: The video content attempts to align with the audio content, such as lip movements and rhythm.

    Billing and rate limiting

    • For the model's free quota and prices, see Models and pricing.

    • For model rate limits, see Wan series.

    • Billing description:

      • Billing is based on the number of seconds of successfully generated video. You are charged only when the query result API returns a task_status of SUCCEEDED, which indicates that a video was successfully generated.

      • No fees are incurred if a model call fails or a processing error occurs. This does not consume your free quota.

    Error codes

    If a call fails, see Error messages for troubleshooting.

    FAQ

    Q: How do I view the model call volume?

    A: One hour after the model call is completed, you can go to the Model Observation (Singapore)Model Observation (Beijing) page to view metrics such as the number of calls and the success rate. 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 convert the link directly. The correct procedure 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 Object Storage Service, to generate a new, permanent access link.

    Example code: Download video to local storage

    import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set a 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 best practice is to have the backend download and save the video and then use a permanent link for playback.