The PixVerse reference-to-video model accepts multiple reference images. It uses a text prompt to describe the scene and blends the subject characters from the assets into a smooth video.
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.
NoteThe sample code in this topic applies to the Singapore region.
HTTP calls
Reference-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. For model output specifications, see Model list. Valid values:
input The basic input information, including the reference images and the prompt. parameters The video generation parameters, such as the video resolution, duration, and whether to generate audio. | Reference-to-videoPass reference images through Python SDKReference-to-video (using ref_name)Pass reference images in |
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 |
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: How do I optimize the result if the prompt does not work well?
A: Try using @ref_name as an alternative.
- Default method: Use the prompt directly. The model automatically parses the reference image content globally, which works for most common scenarios.
- Alternative method: If the generated result deviates from your expectations, use
@ref_nameto specify the reference image in the prompt to improve the result.
Q: How do I use ref_name?
A: ref_name creates a binding between a reference image and the prompt. After you set ref_name for an image in the media array, you can reference the corresponding subject of the reference image in the prompt using the @ref_name syntax.
- For example, if you set
"ref_name": "kitten"in media, use@kittenin the prompt to reference that subject. Note: You must leave a space after @kitten. - Example: @kitten and @puppy are playing on the grass.