The PixVerse reference-to-video model lets you input multiple reference images or videos and a text prompt to describe a scene. The model then merges the main entities from the input media to generate a smooth video.
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 is located.
- Select a URL: Choose the corresponding regional Endpoint URL. The model supports HTTP URLs and DashScope SDK URLs.
- 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 configuring the API key).
The sample code in this document applies to the China (Beijing) region.
HTTP calls
Because reference-to-video tasks can take a long time to complete, typically 1 to 5 minutes, the API uses asynchronous invocation. The process consists of two core steps: Create a task and then Poll for the result. The steps are as follows:
Step 1: Create a task and get the 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 parametersRequest headersContent-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)Basic input information, including reference images and a prompt.
Properties prompt string (Required)The text prompt. Use it to describe the elements and visual features you want in the generated video.Chinese and English are supported. Each Chinese character or letter counts as one character. The character encoding is UTF-8. Any text exceeding the limit is automatically truncated.
@ref_name.
array (Required)A list of media assets used to specify the reference images and videos for video generation.Each element in the array is a media object that contains the type and url fields.
Element properties type string (Required)The type of media asset. Valid values:
string (Required)The media asset URL. Assets include images and videos (videos are only supported by the omni model).
Image input (type=image_url) The reference image URL. It must be a publicly accessible URL.
Video input (type=video_url, omni model only) The reference video URL. It must be a publicly accessible URL.
string (Optional)The name identifier for the entity in the reference image or video. It is used for referencing in the prompt with @ref_name. Maximum 30 characters.object (Required)Video generation parameters. For example, set the video resolution, duration, and whether to generate audio.
Properties resolution string (Required for the omni model)The resolution tier of the output video. Only applicable to the pixverse/pixverse-v6-r2v-omni model.Valid values:
string (Required for the omni model)The aspect ratio of the output video. Only applicable to the pixverse/pixverse-v6-r2v-omni model.Valid values:
string (Required for c1/v6/v5.6 models)The resolution of the generated video, in the format of width*height in pixels. Not supported by the pixverse/pixverse-v6-r2v-omni model.See the tables below for the valid values for different resolution tiers.
pixverse/pixverse-c1-r2v model
pixverse/pixverse-v6-r2v model
pixverse/pixverse-v5.6-r2v model (upgrade to v6 recommended)
integer (Required)The duration of the generated video, in seconds.Valid values:
boolean (Optional)Specifies whether to generate a video with sound. 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 the text is fixed as "AI Generated".
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. |
Pass reference videos and images through media. Use resolution and aspect_ratio to control the output resolution and aspect ratio. |
Response parametersoutputobjectThe output information 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 recommendation: Video generation takes several minutes. We recommend using a polling mechanism with a reasonable query interval, such as 15 seconds, to retrieve the result.
- Task status flow: PENDING → RUNNING → SUCCEEDED / FAILED.
- task_id validity: 24 hours. After this period, queries for the result will fail, and the API will return a task status of
UNKNOWN. - RPS limit: The default records per second (RPS) for the query API is 20. For higher-frequency queries or event notifications, configure an asynchronous task callback.
- More operations: For operations such as batch queries and canceling a task, see Manage asynchronous tasks.
Request parametersRequest headersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.URL 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. 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 format is MP4 (H.264 encoding). Although the video link does not currently expire, you should not rely on it for long-term storage. We recommend that you 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.objectUsage statistics for the output. Only successful tasks are included in the statistics.
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 contains audio.video_count integerThe number of generated videos. The value is fixed at 1.stringUnique request identifier for tracing and troubleshooting. |
|
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: How can I optimize the prompt if the result is not ideal?
A: Try using @ref_name as an alternative.
- Default method: Use the prompt directly. The model automatically parses the content of the reference images globally. This is suitable for most common scenarios.
- Alternative method: If the generated result deviates from your expectations, you can use
@ref_namein the prompt to specify a reference image and improve the result.
Q: How do I use ref_name?
A: The ref_name parameter is used to create a binding between a reference image and the prompt. After setting a ref_name for an image in the media array, you can reference the corresponding entity from the image in the prompt using the @ref_name syntax.
- For example, if you set
"ref_name": "kitten"in the media object, you can use@kittenin the prompt to reference that entity. Note that you must leave a space after @kitten. - Example: @kitten and @puppy are playing on the grass.