All Products
Search

This Product

    Alibaba Cloud Model Studio:Wan - text-to-video API reference (2.1-2.6)

    Document Center

    Alibaba Cloud Model Studio:Wan - text-to-video API reference (2.1-2.6)

    Last Updated:Sep 10, 2026

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

    References: User guide

    Availability

    To ensure successful calls, the model, Endpoint URL, and API Key must all belong to the same region. Cross-region calls will fail.

    NoteThe sample code in this topic applies to the Singapore region.

    ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

    • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
    • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

    {WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

    HTTP

    ImportantThis API uses the legacy protocol and supports wan2.6 and earlier models (wan2.5/wan2.2/wan2.1).

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

    Step 1: Create a task and get the task ID

    Singapore

    POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Replace {WorkspaceId} with your actual workspace ID.

    Virginia

    POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Frankfurt

    POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Replace {WorkspaceId} with your actual workspace ID.

    Beijing

    POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Replace {WorkspaceId} with your actual workspace ID.

    Note

    • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
    • For guidance for beginners, see Call APIs with Postman or cURL.

    Request parameters

    Request headers

    Content-Type string (Required)

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

    Authorization string (Required)

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

    X-DashScope-Async string (Required)

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

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

    Request body

    model string (Required)

    The name of the model to use. For a list of available models, see the model list.

    Example: wan2.6-t2v.

    input object (Required)

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

    The prompt can be in Chinese or English. The length is measured in characters, where each Chinese character or letter is counted as one character. Text that exceeds the character limit is automatically truncated. The length limit varies by model version:

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

    Example: A kitten running in the moonlight.

    For more information, see the Text-to-video/image-to-video prompt guide.

    negative_prompt string (Optional)

    A prompt that describes the content to exclude from the video. This helps refine the generated content.

    The prompt can be in Chinese or English. The maximum length is 500 characters. Text that exceeds this 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 and wan2.5 series models.

    The URL of the audio file. The model will use this audio to generate the video.

    Supported input formats:

    1. Public URL:

    Audio limits:

    • Format: wav, mp3.
    • Duration: 3 to 30 s.
    • File size: Up to 15 MB.
    • Handling audio that exceeds the specified duration: If the audio is longer than the value specified for the duration parameter (for example, 5 seconds), the audio is truncated to the specified duration. If the audio is shorter than the video duration, the remaining part of the video is silent. For example, if the audio is 3 seconds long and the video is 5 seconds long, the first 3 seconds of the video will have audio and the last 2 seconds will be silent.

    parameters object (Optional)

    Video processing parameters, such as setting the video resolution, enabling prompt rewriting, and adding a watermark.

    Properties

    size string (Optional)

    Important

    • The size directly affects the cost. Before making a call, review the model pricing.
    • The size must be set to a specific value, such as 1280*720, not 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 valid values for this parameter depend on the model parameter, as described below:

    • wan2.6-t2v: The default value is 1920*1080 (1080P). Valid resolutions include all resolutions in the 720P and 1080P tiers.
    • wan2.6-t2v-us: The default value is 1920*1080 (1080P). Valid resolutions include all resolutions in the 720P and 1080P tiers.
    • wan2.5-t2v-preview: The default value is 1920*1080 (1080P). Valid resolutions include all resolutions in the 480P, 720P, and 1080P tiers.
    • wan2.2-t2v-plus: The default value is 1920*1080 (1080P). Valid resolutions include all resolutions in the 480P and 1080P tiers.
    • wan2.1-t2v-turbo: The default value is 1280*720 (720P). Valid resolutions include all resolutions in the 480P and 720P tiers.
    • wan2.1-t2v-plus: The default value is 1280*720 (720P). Valid resolutions include all resolutions in the 720P tier.

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

    • 832*480: 16:9.
    • 480*832: 9:16.
    • 624*624: 1:1.

    720P tier: The valid 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 valid 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)

    ImportantThe duration directly affects the cost. Cost = Unit price (based on resolution) × Duration (in seconds). Before making a call, review the model pricing.

    The duration of the generated video in seconds. The valid values for this parameter depend on the model parameter:

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

    prompt_extendboolean (Optional)

    Specifies whether to enable prompt rewriting. When enabled, a model intelligently rewrites the input prompt. This significantly improves the quality of the generated video for shorter prompts but increases the running time.

    • true (default)
    • false

    shot_type string (Optional)

    Supported models: wan2.6 models.

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

    Valid values:

    • single: Default value. Outputs a single-shot video.
    • multi: Outputs a multi-shot video.

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

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

    watermark boolean (Optional)

    Specifies whether to add a watermark. The watermark is placed in the lower-right corner of the video with the fixed text "AI Generated".

    • false (default)
    • true

    seed integer (Optional)

    The random number seed must be an integer in the range [0, 2147483647].

    If not specified, a random seed is generated. A fixed seed improves reproducibility.

    Because model generation is probabilistic, the same seed does not guarantee identical results.

    Multi-shot narrative

    • For a multi-shot video, shot_type must be set to "multi".
    • For a multi-shot video, prompt_extend must be set to true to enable prompt rewriting for shot description optimization.
    
# Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-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"
    }
}'

    Provide an audio file

    Supported models: wan2.6/wan2.5 series models.

    You can provide the URL of a custom audio file using the input.audio_url parameter.

    
# Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.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
    }
}'

    Automatic dubbing

    Supported models: wan2.6/wan2.5 series models.

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

    
# Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.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
    }
}'

    Generate a silent video

    Only the wan2.2 and wan2.1 series models support silent video generation. These models generate silent videos by default, and no additional configuration is required.

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

    
# Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.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-fashioned jacket, holds a guitar, and plays with concentration. Commuters hurry by, 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

    Supported models: All models.

    Use the negative_prompt parameter to exclude the "flower" element and prevent it from appearing in the video.

    
# Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.2-t2v-plus",
    "input": {
        "prompt": "A kitten running in the moonlight",
        "negative_prompt": "flower"
    },
    "parameters": {
        "size": "832*480"
    }
}'

    Response parameters

    output object

    Contains the task output information.

    Properties

    task_id string

    The task ID. Valid for queries for 24 hours.

    task_status string

    The status of the task.

    Enumeration values

    • PENDING
    • RUNNING
    • SUCCEEDED
    • FAILED
    • CANCELED
    • UNKNOWN: The task does not exist or its status is unknown.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    code string

    Error code. Returned only for failed requests. See Error codes.

    message string

    Detailed error message. Returned only for failed requests. See Error codes.

    Successful response

    Save the task_id to query the task status and result.

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

    Error response

    Task creation failed. See Error codes.

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

    Step 2: Query the result by task ID

    Singapore

    GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Replace {WorkspaceId} with your actual workspace ID.

    Virginia

    GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Frankfurt

    GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Replace {WorkspaceId} with your actual workspace ID.

    Beijing

    GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Replace {WorkspaceId} with your actual workspace ID.

    Note

    • Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
    • Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
    • Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
    • task_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

    Request parameters

    Request headers

    Authorization string (Required)

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

    URL path parameters

    task_id string (Required)

    The ID of the task.

    Query task result

    Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

    curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

    Response parameters

    outputobject

    Contains the task output information.

    Properties

    task_id string

    The task ID. Valid for queries for 24 hours.

    task_status string

    The status of the task.

    Enumeration values

    • PENDING
    • RUNNING
    • SUCCEEDED
    • FAILED
    • CANCELED
    • UNKNOWN: The task does not exist or its status is unknown.
    State transitions during polling:
    • PENDING → RUNNING → SUCCEEDED or FAILED.
    • The initial query status is usually PENDING or RUNNING.
    • When the status changes to SUCCEEDED, the response contains the generated video URL.
    • If the status is FAILED, check the error message and retry the task.

    submit_time string

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

    scheduled_time string

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

    end_time string

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

    video_url string

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

    Valid for 24 hours. The video is in MP4 format with H.264 encoding.

    orig_prompt string

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

    actual_prompt string

    When prompt_extend=true, the system rewrites the input prompt. This field returns the optimized prompt 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

    Error code. Returned only for failed requests. See Error codes.

    message string

    Detailed error message. Returned only for failed requests. See Error codes.

    usage object

    Contains statistics about the output. This information is provided only for successful tasks.

    Properties

    video_duration integer

    Returned only when using wan2.5 and earlier models. Used for billing.

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

    duration float

    Returned only when using the wan2.6 model. Used for billing.

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

    input_video_duration integer

    Returned only when using the wan2.6 model. Fixed at 0.

    output_video_duration integer

    Returned only when using 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

    Returned only when using the wan2.6 model. The resolution tier of the generated video. Example: 720.

    size string

    Returned only when using the wan2.6 model. The resolution of the generated video. The format is "widthheight". Example: 19201080.

    video_ratio string

    Returned only when using wan2.5 and earlier models. The resolution of the generated video. The format is "widthheight". Example: 832480.

    video_count integer

    The number of generated videos. Fixed at 1.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    Task successful

    Video URLs are valid for only 24 hours and then automatically purged. Save 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
    }
}

    Task failed

    When a task fails, task_status is FAILED with an error code and message. See Error codes.

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

    Task query expired

    The task_id is valid for 24 hours. After this period, queries return the following error.

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

    DashScope SDK

    The parameter names in the SDK are mostly consistent with the HTTP API, and the parameter structure is encapsulated to align with the features of the programming language.

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

    The actual processing time depends on the number of tasks in the queue and the service status. Wait for the result.

    Python

    ImportantMake sure your DashScope Python SDK version is at least1.25.16 before running the following code.

    If you use an older version, you may encounter errors such as "url error, please check url!". To update the SDK, see Install the SDK.

    Set dashscope.base_http_api_url based on the region where the model is located:

    Singapore

    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    Replace {WorkspaceId} with your actual workspace ID.

    Virginia

    dashscope.base_http_api_url = 'https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1'

    Beijing

    dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

    Replace {WorkspaceId} with your actual workspace ID.

    Frankfurt

    dashscope.base_http_api_url = 'https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1'

    Replace {WorkspaceId} with your actual workspace ID.

    Synchronous invocation

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

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

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

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

if __name__ == '__main__':
    sample_sync_call_t2v()
    Response example

    The video_url is valid for 24 hours. Download promptly.

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

    Asynchronous invocation

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

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

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

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

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

    # Wait for the task to complete. This method calls fetch at intervals and checks if the task is in a finished state.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed. Status code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_async_call_t2v()
    Response example
    1. Example of a response to a task creation request
    {
	"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
}
    1. Example of a response to a task query request

    The video URL expires in 24 hours. Please download the video before it expires.

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

    Java

    ImportantEnsure your DashScope Java software development kit (SDK) version is at least2.22.14 before you run the following code.

    If you use an older version, you may encounter errors such as "url error, please check url!". To update the SDK, see Install the SDK.

    Set Constants.baseHttpApiUrl based on the region where the model is located:

    Singapore

    Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

    Replace {WorkspaceId} with your actual workspace ID.

    Virginia

    Constants.baseHttpApiUrl = "https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1";

    Beijing

    Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

    Replace {WorkspaceId} with your actual workspace ID.

    Frankfurt

    Constants.baseHttpApiUrl = "https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1";

    Replace {WorkspaceId} with your actual workspace ID.

    Synchronous invocation

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

// dashscope SDK version 2.18.2 or later
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.HashMap;
import java.util.Map;

public class Text2Video {

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

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

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

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

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

    The video_url is valid for 24 hours. Download promptly.

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

    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 {
    static {
        // The URL for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region. For more information, see https://www.alibabacloud.com/help/model-studio/text-to-video-api-reference
        Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

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

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

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

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

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

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

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

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
    Response example
    1. Example of a response to a task creation request.
    {
        "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}
    1. Example of a response to a task query request

    The video_url is valid for 24 hours. Download promptly.

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

    Error codes

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

    FAQ

    A: You cannot convert the link directly. The correct procedure is to have your backend service retrieve the URL, download the video file, and then upload it to a permanent object storage service, such as Alibaba Cloud Object Storage Service (OSS), to generate a new, permanent access link.

    Example code: Download a video to a local device

    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}")
        # Add the logic to upload to permanent storage here
    except requests.exceptions.RequestException as e:
        print(f"Failed to download the 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)

    A: No. You should not play the link directly in a browser because it expires after 24 hours. Instead, you should download and store the video, and then use a permanent link for playback.