The PixVerse text-to-video model generates a smooth video based on a text prompt.
ImportantThis document applies only to the Singapore region. You must use an API key from this region.
Activate the service
- Go to the Model Studio console, search for PixVerse, find the PixVerse model card, and click Activate Now.
- In the pop-up window, confirm the activation and authorization.
Usage notes
To ensure successful API calls, you must use a model, endpoint URL, and API key that all belong to the same region. Cross-region calls will fail.
- Select a model: Confirm the region where your model is located.
- Select a URL: Choose the corresponding regional endpoint URL. Both HTTP and DashScope SDK URLs are supported.
- Configure an API key: Select a region, get an API key, and then configure the API key as an environment variable.
- Install the SDK: To make calls using an SDK, install the DashScope SDK.
NoteThe sample code in this topic applies to the Singapore region.
HTTP calls
Text-to-video generation is a long-running task that typically takes 1 to 5 minutes, so the API uses asynchronous calls. The workflow consists of two core steps: "Create a task -> Poll for the result". The steps are as follows:
Step 1: Create a task to get a task ID
Singapore region: POST https://{WorkspaceId}.ap-southeast-1.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_idto query the result. Thetask_idis 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 parametersHeadersContent-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. X-DashScope-Async Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request bodymodel The model name. Valid values:
input The basic input information, such as the prompt. parameters The video generation parameters, such as the video resolution, duration, and whether to generate audio. | Text-to-videoSupported model: pixverse/pixverse-v6-t2v. Text-to-video (multi-shot)Supported model: pixverse/pixverse-v6-t2v. Describe the multi-shot scene in the |
Response parametersoutput Task output information. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | Successful responseSave the Error responseTask creation failed. See Error codes. |
Step 2: Query the result by task ID
Singapore region: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Note
- Polling recommendation: Video generation can take several minutes. Use a polling mechanism and poll for the result at a reasonable interval, such as every 15 seconds.
- Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
- Task ID validity: The
task_idis valid for 24 hours. After this period, queries will fail and the API returns a task status ofUNKNOWN. - RPS limit: The query endpoint has a default limit of 20 RPS. For high-frequency queries or event notifications, configure asynchronous task callbacks.
- More operations: To perform batch queries, cancel tasks, or run other operations, see Manage asynchronous tasks.
Request parametersHeadersAuthorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Path parameterstask_id The ID of the task. | Query task resultReplace |
Response parametersoutput Task output information. usage Output usage statistics, counted only for successful tasks. request_id Unique request identifier for tracing and troubleshooting. | Task succeededTask failedWhen a task fails, Task query expiredThe |
DashScope SDK calls
The parameter names in the SDK are mostly consistent with the HTTP API. The parameter structure is adapted to the features of each programming language.
Because text-to-video tasks take a long time (typically 1 to 5 minutes), the SDK encapsulates the HTTP asynchronous call process and supports both synchronous and asynchronous call methods.
The actual time required depends on the number of queued tasks and the service execution status. Please be patient while waiting for the result.
Python SDK calls
ImportantMake sure that your DashScope Python SDK version is not earlier than 2.0.1 before running the following code.
An earlier version might trigger errors such as "url error, please check url!". To update the SDK, see Install the SDK.
Singapore region: region="ap-southeast-1"
Replace {WorkspaceId} with your actual workspace ID.
Synchronous call
Request example
import os
import dashscope
from dashscope.v2 import DashScopeError
# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
# If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def sample_sync_call_t2v():
# Call the synchronous API, which returns the result directly.
print('please wait...')
# generate is a one-step call (submits the task and waits for completion) that returns a completed Job.
# audio is a parameters-section field, not in the named signature; pass it through parameters.
try:
job = client.videos.generate(model='pixverse/pixverse-v6-t2v',
prompt='In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.',
size='1280*720',
duration=5,
watermark=False,
parameters={'audio': False})
print(job)
print(job.video_url)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_sync_call_t2v()
Response example
video_urldoes not currently expire, but it is not intended for long-term storage. Download the video promptly.
{
"request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
"task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"video_url": "https://media.pixverseai.cn/xxx.mp4"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"video_duration": 0,
"video_ratio": "",
"duration": 10,
"size": "1280x720",
"fps": 24,
"audio": false,
"SR": "720"
}
}
Asynchronous call
Request example
import os
import dashscope
from dashscope.v2 import DashScopeError
# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
# If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def sample_async_call_t2v():
# Submit the asynchronous task and return the task information immediately
# audio is a parameters-section field, not in the named signature; pass it through parameters.
try:
job = client.videos.jobs.create(model='pixverse/pixverse-v6-t2v',
prompt='In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.',
size='1280*720',
duration=5,
watermark=True,
parameters={'audio': False})
print(job)
print("task_id: %s" % job.task_id)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
return
# Query task status
try:
snapshot = client.videos.jobs.fetch(job.task_id)
print(snapshot.status) # Check the task status.
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
# Wait for the task to complete (exponential backoff polling, default total budget of 24 hours)
try:
done = client.videos.jobs.wait(job)
print(done)
print(done.video_url)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_async_call_t2v()
Response example
- Response example for creating a task.
{
"request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
"status": "PENDING"
}
- Response example for querying a task result
video_urldoes not currently expire, but it is not intended for long-term storage. Download the video promptly.
{
"request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
"task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"video_url": "https://media.pixverseai.cn/xxx.mp4"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"video_duration": 0,
"video_ratio": "",
"duration": 10,
"size": "1280x720",
"fps": 24,
"audio": false,
"SR": "720"
}
}
Java SDK calls
ImportantMake sure that your DashScope Java SDK version is not earlier than 2.22.6 before running the following code.
An earlier version might trigger errors such as "url error, please check url!". To update the SDK, see Install the SDK.
Singapore region: Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
Replace {WorkspaceId} with your actual workspace ID.
Synchronous call
Request example
// Replace {WorkspaceId} with your actual workspace ID.
// 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 Singapore region.
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
// To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Create a video compositing task and wait for the task to complete.
*/
public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("pixverse/pixverse-v6-t2v")
.prompt("In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.")
.size("1280*720")
.duration(5)
.audio(true)
.watermark(true)
.seed(12345)
.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
video_urldoes not currently expire, but it is not intended for long-term storage. Download the video promptly.
{
"request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
"output": {
"task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://media.pixverseai.cn/xxx.mp4",
"orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
"submit_time": "2026-03-20 11:21:13.227",
"scheduled_time": "2026-03-20 11:21:13.252",
"end_time": "2026-03-20 11:21:43.924"
},
"usage": {
"video_count": 1,
"duration": 5.0,
"size": "1280*720",
"input_video_duration": 0.0,
"output_video_duration": 0.0,
"SR": "720"
},
"status_code": 200,
"code": "",
"message": ""
}
Asynchronous call
Request example
// Replace {WorkspaceId} with your actual workspace ID.
// 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;
public class Text2Video {
static {
// The following is the URL for the Singapore region.
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
// To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Create a video compositing task and wait for the task to complete.
*/
public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("pixverse/pixverse-v6-t2v")
.prompt("In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.")
.size("1280*720")
.duration(5)
.audio(true)
.watermark(true)
.seed(12345)
.build();
// 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 a single task result.
public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
VideoSynthesis is = new VideoSynthesis();
// If the DASHSCOPE_API_KEY environment variable is set, apiKey can be null.
VideoSynthesisResult result = is.fetch(taskId, apiKey);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args) {
try {
text2Video();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
Response example
- 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": ""
}
- Response example for querying a task result
video_urldoes not currently expire, but it is not intended for long-term storage. Download the video promptly.
{
"request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
"output": {
"task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://media.pixverseai.cn/xxx.mp4",
"orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
"submit_time": "2026-03-20 11:21:13.227",
"scheduled_time": "2026-03-20 11:21:13.252",
"end_time": "2026-03-20 11:21:43.924"
},
"usage": {
"video_count": 1,
"duration": 5.0,
"size": "1280*720",
"input_video_duration": 0.0,
"output_video_duration": 0.0,
"SR": "720"
},
"status_code": 200,
"code": "",
"message": ""
}
Error codes
If the model call fails and returns an error message, see Error codes for resolution.