The PixVerse image-to-video model generates a smooth video from an input image and a text prompt.
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: Get an API key for the region, and then configure the API key as an environment variable.
The sample code in this topic applies to the Singapore region.
HTTP calls
Image-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.
- 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:
object (Required)The basic input information, such as the prompt and media assets.
Properties prompt string (Optional)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.
array (Required)A list of media assets that specifies the image required for video generation.Each element in the array is a media object that contains the type and url fields.
Properties type string (Required)The type of the media asset. Fixed value:
If you provide multiple images, the system uses the last one by default. To ensure expected results, always provide only one image.url string (Required)The URL of the image file. The URL must be publicly accessible.
object (Required)Video processing parameters, such as the video resolution, video duration, audio generation, and watermark.
Properties resolution string (Required)Specifies the resolution tier of the generated video.Valid values: 360P, 540P, 720P, and 1080P.duration 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 fixed text "AI Generated".
string (Optional)Supported model: pixverse/pixverse-v6-it2v.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 model: pixverse/pixverse-v6-it2v. |
Response parametersoutputobjectTask output information.
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
Singapore region: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
- 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 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 parametersoutputobjectTask 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. The format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The format is YYYY-MM-DD HH:mm:ss.SSS.video_url stringThe 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 do not rely on it for long-term storage. Download the video promptly.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.objectOutput usage statistics, counted only for successful tasks.
Properties duration integerThe total duration of the generated video, 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_type stringThe shot type of the generated video.stringUnique request identifier for tracing and troubleshooting. |
|