Skip to main content

PixVerse - Reference-to-video API reference

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.

This document applies only to the Singapore region. You must use an API key from this region.

Activate the service

  1. Go to the Model Studio console, search for PixVerse, find the PixVerse model card, and click Activate Now.
  2. 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.
The 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.
  • After the task is created, use the returned task_id to query the result. The task_id is 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 parameters

Headers
Content-Type string (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.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model string (Required)The model name. For model output specifications, see Model list.Valid values:
  • pixverse/pixverse-v6-r2v
input object (Required)The basic input information, including the reference images and 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.
  • pixverse/pixverse-v6-r2v: Up to 2,048 characters.
Image reference instructions: When you pass a reference image in the media parameter, you can directly reference it in the prompt using @ref_name.
  • The ref_name set in media must be globally unique within the same request and must correspond one-to-one with the references in the prompt.
  • Formatting rule: You must leave a space after @ref_name as a separator.
Examples:
  • Plain prompt: A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop.
  • Prompt with references: @man sits on a chair by the window, holding @guitar , playing a soothing American country folk song next to @coffeeshop .
media array (Required)A list of media assets that specifies the reference images required 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 the media asset. Fixed value:
  • image_url: An image URL.
Asset quantity limit: Up to 7 images.url string (Required)The URL of the reference image. The URL must be publicly accessible.Image limits:
  • Format: JPG, PNG, or WEBP.
  • Resolution: The width and height of the image cannot exceed 10,000 pixels.
  • File size: Up to 20 MB.
ref_name string (Optional)The name identifier of the subject in the reference image. It is used to reference the image in the prompt with @ref_name. Up to 30 characters.
parameters 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 table lists the valid values for different resolution tiers.

pixverse/pixverse-v6-r2v model

Resolution tier

Aspect ratio

size value (width*height)

360P

16:9

640*360

4:3

640*480

1:1

640*640

3:4

480*640

9:16

360*640

3:2

640*432

2:3

432*640

21:9

640*288

540P

16:9

1024*576

4:3

1024*768

1:1

1024*1024

3:4

768*1024

9:16

576*1024

3:2

1024*688

2:3

688*1024

21:9

1024*448

720P

16:9

1280*720

4:3

1108*832

1:1

960*960

3:4

832*1108

9:16

720*1280

3:2

1200*800

2:3

800*1200

21:9

1280*560

1080P

16:9

1920*1080

4:3

1664*1248

1:1

1440*1440

3:4

1248*1664

9:16

1080*1920

3:2

1776*1184

2:3

1184*1776

21:9

1920*832

Example: 1280*720.duration integer (Required)
The duration parameter directly affects the cost. Before making a call, confirm the pricing of PixVerse - Reference-to-video.
The duration of the generated video, in seconds.
  • pixverse/pixverse-v6-r2v: An integer in the range [1, 15].
Example: 5.audio boolean (Optional)
The audio parameter directly affects the cost. Before making a call, confirm the pricing of PixVerse - Reference-to-video.
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.
  • false: Default value. Outputs a silent video.
  • true: Outputs a video with audio.
Example: false.watermark 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".
  • false: Default value. No watermark is added.
  • true: A watermark is added.
Example: false.seed 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.
  • Reference-to-video
  • Python SDK
  • Reference-to-video (using ref_name)
Pass reference images through media, and set size and duration to control the video resolution and duration.
# Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING: The task is queued.
  • RUNNING: The task is being processed.
  • SUCCEEDED: The task succeeded.
  • FAILED: The task failed.
  • CANCELED: The task was canceled.
  • UNKNOWN: The task does not exist or its status is unknown.
request_id 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.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

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_id is valid for 24 hours. After this period, queries will fail and the API returns a task status of UNKNOWN.
  • 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 parameters

Headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Path parameters
task_id string (Required)The ID of the task.
  • Query task result
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.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING: The task is queued.
  • RUNNING: The task is being processed.
  • SUCCEEDED: The task succeeded.
  • FAILED: The task failed.
  • CANCELED: The task was canceled.
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
  • The initial query status is usually PENDING (queued) or RUNNING (processing).
  • When the status changes to SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry.
  • If the status is CANCELED, the task was canceled. To continue, submit the task again.
  • If the status is UNKNOWN, the task does not exist or its status is unknown. This can occur if the task_id does not exist or has passed its 24-hour validity period.
submit_time 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.
usage 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.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
  • Task query expired
{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

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_name to 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 @kitten in the prompt to reference that subject. Note: You must leave a space after @kitten.
  • Example: @kitten and @puppy are playing on the grass.