The PixVerse text-to-video model generates a smooth video based on text prompts .
Activate the service
- Go to the Alibaba Cloud 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.
Scope
To ensure successful calls, make sure that the model, Endpoint URL, and API key all belong to the same region. Cross-region calls will fail.
- Select a model: Confirm the region where the model belongs.
- Select a URL: Choose the corresponding regional Endpoint URL. HTTP URLs and DashScope SDK URLs are supported.
- Configure an API key: Select a region and obtain an API key. Then, configure the API key as an environment variable (This method is being deprecated and will be merged into the standard API key configuration).
- Install the SDK: To make calls using an SDK, install the DashScope SDK.
HTTP calls
Because text-to-video tasks take a long time (typically 1 to 5 minutes), the API uses asynchronous calls. The entire process involves 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
Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Replace {WorkspaceId} with your actual workspace ID.
- 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-Typestring (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.Request Bodymodelstring (Required)The model name.Valid values:
Model selection
object (Required)The basic input information, such as the prompt.
Properties prompt string (Required)The text prompt. It describes the desired elements and visual features in the generated video.Both Chinese and English are supported. Each Chinese character or letter counts as one character. The character encoding is UTF-8. Any excess characters are automatically truncated.
object (Required)The video generation parameters, such as the video resolution, duration, and whether to generate audio.
Properties size string (Required)The resolution of the generated video, in the format of width*height in pixels.The following tables list the valid values for different resolution tiers and aspect ratios.
pixverse/pixverse-c1-t2v and pixverse/pixverse-v6-t2v models
pixverse/pixverse-v5.6-t2v model
integer (Required)The duration of the generated video, in seconds.
boolean (Optional)Specifies whether to generate a video with audio. If enabled, the model automatically generates matching background music or sound effects based on the video content.
boolean (Optional)Specifies whether to add a watermark. The watermark is located in the lower-right corner of the video and displays the text "AI Generated".
string (Optional)Supported model: pixverse/pixverse-v6-t2v.Specifies the shot type of the generated video. This controls whether the video consists of a single continuous shot or multiple shots.
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. |
Supported models: pixverse/pixverse-c1-t2v, pixverse/pixverse-v6-t2v, pixverse/pixverse-v5.6-t2v. |
Response parametersoutputobjectThe output of the task.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes. |
Save the task_id to query the task status and result. |
Step 2: Query the result by task ID
Beijing region: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
- Polling suggestion: Video generation takes several minutes. We recommend using a polling mechanism with a reasonable query interval (for example, 15 seconds) to obtain the result.
- Task status flow: PENDING (in queue) -> RUNNING (processing) -> SUCCEEDED (successful) / FAILED (failed).
- task_id validity: 24 hours. After this period, you cannot query the result, and the API will return the task status as
UNKNOWN. - RPS limit: The default records per second (RPS) for the query API is 20. For higher frequency queries or event notifications, we recommend configuring an asynchronous task callback.
- More operations: For batch queries, canceling tasks, and other operations, see Manage asynchronous tasks.
Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
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. |
Response parametersoutputobjectThe task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.video_urlstringThe video URL. This is returned only when task_status is SUCCEEDED.The video is in MP4 format (H.264 encoding). The video link does not currently expire, but we recommend downloading it for long-term storage.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectStatistics for the output information. Only successful results are counted.
Properties duration integerThe total duration of the generated video in seconds, used for billing.size stringThe resolution of the generated video.fps integerThe frame rate of the generated video.SR stringThe resolution tier of the generated video.audio booleanIndicates whether the generated video has audio.video_count integerThe number of generated videos. The value is fixed at 1.shot_typestringThe shot type of the generated video.stringUnique request identifier for tracing and troubleshooting. |
|
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 specific time required depends on the number of tasks in the queue and the service execution status. Please be patient while waiting for the result.
Python SDK calls
Beijing region: dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
Replace {WorkspaceId} with your actual workspace ID.
- Synchronous call
- Asynchronous call
Request example
Response example
video_url does not expire, but it is not intended for long-term storage. We recommend that you download the video promptly.
Java SDK calls
Beijing region: Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
Replace {WorkspaceId} with your actual workspace ID.
- Synchronous call
- Asynchronous call
Request example
Response example
video_url does not expire. It is not intended for long-term storage, so you should download it promptly.
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: Why can't I use a 10-second duration with 1080P resolution?
A: The pixverse-v5.6-t2v model does not support a 10-second duration at 1080P. We recommend reducing the resolution to 720P, 540P, or 360P, or switching to the pixverse-c1-t2v or pixverse-v6-t2v model.