Vidu Text-to-Video API reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Service activation

Go to the Alibaba Cloud Model Studio console, search for Vidu, find the Vidu model card, and click Activate Now. In the dialog box, confirm the activation and authorization.

Prerequisites

To ensure successful calls, make sure the model, endpoint URL, and API key are all in the same region. Cross-region calls will fail.

Select a model: Confirm the model's region.
Select a URL: Select the endpoint URL that corresponds to your region. You can use an HTTP URL or a DashScope SDK URL.
Configure the API key: Select a region, get an API key, and then set the API key as an environment variable.
Install the SDK: To make calls using the SDK, install the DashScope SDK.

HTTP calls

Because text-to-video tasks are time-consuming (typically 1–5 minutes), the API uses an asynchronous call. The process consists of two core steps: "Create a task -> Poll for results".

Step 1: Create a task

China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.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. Instead, use polling to retrieve the result.
For guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Text-to-video

curl --location 'https://{WorkspaceId}.cn-beijing.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": "vidu/viduq3-turbo_text2video",
    "input": {
        "prompt": "A kitten running in the moonlight"
    },
    "parameters": {
        "size": "1024*576",
        "resolution": "540P",
        "duration": 5,
        "watermark": true
    }
}'

Request headers

Content-Type string (Required)

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

X-DashScope-Async string (Required)

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

Important

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

Request body

model string (Required)

The model name. Valid values:

vidu/viduq3-pro_text2video
vidu/viduq3-turbo_text2video
vidu/viduq2_text2video

input object (Required)

The model's input, such as the prompt.

Properties

prompt string (Required)

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

Both Chinese and English are supported. Each Chinese character or letter is counted as one character. The prompt cannot exceed 5,000 characters; any text beyond this limit is automatically truncated.

Example: A kitten running in the moonlight.

For more information about how to write prompts, see Vidu Video Generation Prompt Guide.

parameters object (Optional)

Parameters for video generation, such as resolution and duration.

Properties

resolution string (Optional)

Important

Resolution directly affects cost. Check Model Pricing before you call the API.

The resolution tier. Valid values:

540P
720P: Default.
1080P

size string (Optional)

The resolution of the generated video, in pixels, in the format width*height.

The default value depends on resolution:

When the resolution is 540P, the size defaults to 1024*576.
When resolution=720P, size defaults to 1280*720.
When resolution=1080P, size defaults to 1920*1080.

Resolution tier	Aspect ratio	*Size (widthheight)**
540P	16:9	1024*576
	9:16	576*1024
	1:1	1024*1024
	4:3	1024*768
	3:4	768*1024
720P	16:9	1280*720
	9:16	720*1280
	1:1	1280*1280
	4:3	1280*960
	3:4	960*1280
1080P	16:9	1920*1080
	9:16	1080*1920
	1:1	1808*1808
	4:3	1920*1440
	3:4	1440*1920

duration integer (Optional)

Important

Duration directly affects cost, as billing is per second. Check Model Pricing before you call the API.

The duration of the generated video, in seconds.

vidu/viduq3-pro_text2video, vidu/viduq3-turbo_text2video: The value is an integer in the range of [1, 16]. The default value is 5.
vidu/viduq2_text2video: The value is an integer from 1 to 10. The default value is 5.

audio boolean (Optional)

Supported models: vidu/viduq3-pro_text2video, vidu/viduq3-turbo_text2video.

Specifies whether to generate a video with audio. If set to true, the model automatically generates matching background music or sound effects based on the video content.

false: Default. Outputs a video without audio.
true: Outputs a video with audio.

watermark boolean (Optional)

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

false: Default. No watermark is added.
true: Adds a watermark.

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.

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 Task creation failed. See Error codes. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Details of the task output. 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.

Step 2: Query task result

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

Note

Polling recommendation: Video generation can take several minutes. We recommend using a polling mechanism with a reasonable query interval (e.g., 15 seconds) to retrieve the result.
Task status flow: PENDING (queued) → RUNNING (in progress) → SUCCEEDED (succeeded) / FAILED (failed).
task_id validity: 24 hours. After this period, you can no longer query the result, and the API returns a task status of UNKNOWN.
RPS limit: The query endpoint has a default RPS (Requests Per Second) limit of 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.
More operations: For operations such as bulk queries or canceling tasks, see Manage Asynchronous Tasks.

Request parameters	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. `curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Request headers
Authorization `string` (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Path parameters
task_id `string` (Required) The ID of the task.

Response parameters	Task succeeded Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. { "request_id": "eda50dad-a6d3-4e62-a70b-26bbb797ae81", "output": { "task_id": "d9254244-1f9b-4b4c-be82-d9560ba25708", "task_status": "SUCCEEDED", "submit_time": "2026-03-27 13:32:13.962", "scheduled_time": "2026-03-27 13:32:14.008", "end_time": "2026-03-27 13:32:43.375", "orig_prompt": "A kitten running in the moonlight", "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx" }, "usage": { "duration": 5, "size": "960*528", "output_video_duration": 5, "fps": 24, "video_count": 1, "audio": false, "SR": "540" } } 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" } }`
output `object` Information about the task output. 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. format is YYYY-MM-DD HH:mm:ss.SSS. scheduled_time `string` The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS. end_time `string` The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS. video_url `string` The URL of the generated video. This is returned only when the `task_status` is `SUCCEEDED`. The video is in MP4 format (H.264 encoded). The video URL is valid for 24 hours. Please download it promptly. orig_prompt `string` The original input prompt, corresponding to the request parameter `prompt`. 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` Statistics for the output, counted only for successful tasks. Properties duration `integer` Total billable video duration, in seconds. Example: 5. output_video_duration `integer` The duration of the output video, in seconds. Example: 5. size `string` The resolution of the output video. Example: 960528. fps* `integer` The frame rate of the output video. Example: 24. SR `string` The resolution tier of the generated video. Example: 540. audio `boolean` Indicates whether the generated video includes audio. Example: false. video_count `integer` The number of generated videos. This value is always 1.
request_id `string` Unique request identifier for tracing and troubleshooting.

SDK calls

The parameter names in the SDK are largely consistent with the HTTP interface, and the parameter structure is adapted to the features of each programming language.

Because text-to-video tasks are time-consuming (typically 1-5 minutes), the SDK encapsulates the asynchronous HTTP call process and supports both synchronous and asynchronous calls.

The actual processing time depends on the number of tasks in the queue and the service's operational status. Be patient when retrieving the results.

Python

Important

Ensure the DashScope Python SDK version is at least 1.25.8 before running the following code.

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

Synchronous call

Request example

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# The following is the URL for the China (Beijing) region
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.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"
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_t2v():
    # Make a synchronous call, which waits for and returns the result.
    print('please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model='vidu/viduq3-turbo_text2video',
                              prompt='A kitten running under moonlight',
                              size='1024*576',
                              duration=5,
                              resolution='540P',
                              watermark=True)
    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 the video promptly.

{
    "status_code": 200,
    "request_id": "15bd86e5-28b1-40ad-a427-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "a876c6ee-1c63-4d17-b6c0-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx",
        "submit_time": "2026-03-27 13:35:49.508",
        "scheduled_time": "2026-03-27 13:35:49.540",
        "end_time": "2026-03-27 13:36:45.848",
        "orig_prompt": "A kitten running under moonlight"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "audio": false,
        "SR": "540"
    }
}

Asynchronous call

Request example

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# The following is the URL for the China (Beijing) region
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.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"
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_t2v():
    # Make an asynchronous call, which returns task information immediately.
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model='vidu/viduq3-turbo_text2video',
                                    prompt='A kitten running under moonlight',
                                    size='1024*576',
                                    duration=5,
                                    resolution='540P')
    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, 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.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_async_call_t2v()

Response example

1. Response example for creating a task

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

2. Response example for querying the task status

The video_url is valid for 24 hours. Download the video promptly.

{
    "status_code": 200,
    "request_id": "15bd86e5-28b1-40ad-a427-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "a876c6ee-1c63-4d17-b6c0-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx",
        "submit_time": "2026-03-27 13:35:49.508",
        "scheduled_time": "2026-03-27 13:35:49.540",
        "end_time": "2026-03-27 13:36:45.848",
        "orig_prompt": "A kitten running under moonlight"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "audio": false,
        "SR": "540"
    }
}

Java

Important

Ensure the DashScope Java SDK version is at least 2.22.6 before running the following code.

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

Synchronous call

Request example

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

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {

    static {
        // The following is the URL for the China (Beijing) region
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured an environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Create a video synthesis task and wait for it to complete.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("vidu/viduq3-turbo_text2video")
                        .prompt("A kitten running under moonlight")
                        .size("1024*576")
                        .resolution("540P")
                        .duration(5)
                        .watermark(true)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            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 the video promptly.

{
    "request_id": "bebc5f6b-a081-4b02-ad29-xxxxxx",
    "output": {
        "task_id": "2b0e287f-ebdc-49af-82aa-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/infer_92/xxx.mp4?xxx",
        "orig_prompt": "A kitten running under moonlight",
        "submit_time": "2026-03-30 10:19:00.827",
        "scheduled_time": "2026-03-30 10:19:00.879",
        "end_time": "2026-03-30 10:19:28.172"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "size": "960*528",
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "SR": "540"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Asynchronous call

Request example

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

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {

    static {
        // The following is the URL for the China (Beijing) region
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured an environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Creates a video synthesis task asynchronously and then waits for its completion.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("vidu/viduq3-turbo_text2video")
                        .prompt("A kitten running under moonlight")
                        .size("1024*576")
                        .resolution("540P")
                        .duration(5)
                        .watermark(true)
                        .build();

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

        // Fetch the result
        VideoSynthesisResult result = vs.wait(task, apiKey);
        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

1. Response example for creating a task

{
    "request_id": "9b583f1b-2423-4fac-bb3f-xxxxxx",
    "output": {
        "task_id": "3944b819-1bbb-4da0-a230-xxxxxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

2. Response example for querying the task status

The video_url is valid for 24 hours. Download the video promptly.

{
    "request_id": "bebc5f6b-a081-4b02-ad29-xxxxxx",
    "output": {
        "task_id": "2b0e287f-ebdc-49af-82aa-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/infer_92/xxx.mp4?xxx",
        "orig_prompt": "A kitten running under moonlight",
        "submit_time": "2026-03-30 10:19:00.827",
        "scheduled_time": "2026-03-30 10:19:00.879",
        "end_time": "2026-03-30 10:19:28.172"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "size": "960*528",
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "SR": "540"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Error codes

If a model call fails, see error message for troubleshooting.

FAQ

Q: Must `size` and `resolution` be passed together?

A: No. Both are optional parameters, but passing both is recommended to precisely control the aspect ratio of the generated video. For details, see size values.

If you do not pass both parameters, the system handles the request in one of the following two ways:

Pass only size: The size parameter is ignored, and the system defaults to resolution=720P and uses the corresponding size of 1280*720.

Example: The API response is size="1280*720", SR=720.
Pass only resolution: The system generates a video at the specified resolution tier with a corresponding 16:9 aspect ratio.

Example: When resolution=540P, the API response is size="960*540", SR=540; when resolution=1080P, the API response is size="1920*1080", SR=1080.

Service activation

Prerequisites

HTTP calls

Step 1: Create a task

Request parameters

Text-to-video

Request headers

Request body

Response parameters

Successful response

Error response

Step 2: Query task result

Request parameters

Query task result

Request headers

Path parameters

Response parameters

Task succeeded

Task failed

Task query expired

SDK calls

Python

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Java

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Error codes

FAQ

Q: Must size and resolution be passed together?

Q: Must `size` and `resolution` be passed together?