DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Video Generation PixVerse PixVerse - Reference-to-video

PixVerse reference-to-video API reference

Updated at:
Copy as MD
Product
My Favorites

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.

ImportantThis document applies only to the China (Beijing) region. Use an API key from this region.

Activate the service

  1. Go to the Alibaba Cloud 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.

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.

NoteThe 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.

Note

  • 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

Request 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.

ImportantIf 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.

Valid values:

  • pixverse/pixverse-v6-r2v-omni
  • pixverse/pixverse-c1-r2v
  • pixverse/pixverse-v6-r2v
  • pixverse/pixverse-v5.6-r2v

Model selection

  • For image + video fusion reference-to-video generation, use v6-r2v-omni.
  • For dynamic scenarios such as fights, magic effects, and high-speed motion, and for multi-grid scenarios, use c1.
  • For general scenarios, v6 is recommended. We recommend upgrading v5.6 to v6.

input 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.

  • pixverse/pixverse-v6-r2v-omni: Up to 5000 characters.
  • pixverse/pixverse-c1-r2v: Up to 5000 characters.
  • pixverse/pixverse-v6-r2v: Up to 2048 characters.
  • pixverse/pixverse-v5.6-r2v: Up to 2048 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 reference in the prompt.
  • Formatting rule: You must leave a space after @ref_name as a separator.

Examples:

  • Normal 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 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:

  • image_url: Image URL.
  • video_url: Video URL. Only supported by the omni model.

Asset quantity limits:

  • Number of images: Up to 10 for the omni model, up to 7 for other models.
  • Number of videos: 1 to 2 (omni model only).

url 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.

Image limits:

  • Format: JPG, PNG, WEBP.
  • Resolution: The width and height of the image must not exceed 10000 pixels.
  • File size: Up to 20 MB.

Video input (type=video_url, omni model only)

The reference video URL. It must be a publicly accessible URL.

Video limits:

  • Format: MP4, MOV.
  • Resolution: The long side must not exceed 1920 pixels.
  • File size: Up to 50 MB per video.
  • Duration: Total duration of all videos must not exceed 15 seconds.

ref_name 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.

parameters 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:

  • 360P
  • 540P
  • 720P
  • 1080P

aspect_ratio 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:

  • auto: Uses the aspect ratio of the first input image or video.
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
  • 3:2
  • 2:3
  • 21:9

size 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

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

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)

ImportantThe duration parameter directly affects the cost. For more information, see iCoser reference-to-video before making a call.

The duration of the generated video, in seconds.

Valid values:

  • pixverse/pixverse-v6-r2v-omni:

    • When using video references: Must be set to 0. The system automatically uses the duration of the longest input video.
    • When using image references only: An integer from 1 to 15.

  • pixverse/pixverse-c1-r2v: An integer from 1 to 15.

  • pixverse/pixverse-v6-r2v: An integer from 1 to 15.

  • pixverse/pixverse-v5.6-r2v:

    • When size is any resolution corresponding to 360P, 540P, or 720P: The value can be 5, 8, or 10.
    • When size is any resolution corresponding to 1080P: The value can be 5 or 8.

Example: 5.

audio boolean (Optional)

ImportantThe audio parameter directly affects the cost. Before making a call, confirm the billing details for PixVerse reference-to-video.

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.

  • false: Default. Outputs a silent video.
  • true: Outputs a video with sound.

Example: false.

watermark 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".

  • false: Default. 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 (image + video, omni)

Pass reference videos and images through media. Use resolution and aspect_ratio to control the output resolution and aspect ratio.

# Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.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-omni",
    "input": {
        "media": [
            {
                "type": "video_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "ref_name": "refvideo"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg",
                "ref_name": "man"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "coffeeshop"
            }
        ],
        "prompt": "@man plays guitar in @coffeeshop refer to @refvideo"
    },
    "parameters": {
        "resolution": "720P",
        "aspect_ratio": "16:9",
        "duration": 0,
        "audio": true,
        "watermark": false
    }
}'

Python SDK

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you have not configured environment variables, replace the following line with your API Key: api_key="sk-xxx"
# Get API Key: https://help.aliyun.com/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

media = [{'type': 'video_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4', 'ref_name': 'reference video'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg', 'ref_name': 'man'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png', 'ref_name': 'coffee shop'}]

def sample_async_call():
    # Submit video generation task asynchronously
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                model='pixverse/pixverse-v6-r2v-omni',
                                media=media,
                                prompt='@man plays guitar in @coffee shop refer to @reference video',
                                resolution='720P',
                                aspect_ratio='16:9',
                                duration=0,
                                audio=True,
                                watermark=False)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # Query task status
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for task to complete
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_async_call()

Reference-to-video

Pass reference images through media. Set size and duration to control the video resolution and duration.

# Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.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-c1-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
    }
}'

Reference-to-video (using ref_name)

Pass reference images in media and pass ref_name to set the entity name for the reference image.

# Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.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-c1-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",
                "ref_name": "man"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "ref_name": "guitar"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "coffeeshop"
            }
        ],
        "prompt": "@man sits on a chair by the window, holding @guitar, playing a soothing American country folk song next to @coffeeshop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Response parameters

output object

The output information of the task.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Step 2: Query the result by task ID

Beijing region: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • 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 parameters

Request headers

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

URL 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}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobject

Task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING → RUNNING → SUCCEEDED or FAILED.
  • The initial query status is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry the task.

submit_time string

The time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

video_urlstring

The 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 string

The original input prompt, corresponding to the request parameter prompt.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

Usage statistics for the output. Only successful tasks are included in the statistics.

Properties

duration integer

The total duration of the generated video, used for billing.

size string

The resolution of the generated video.

fps integer

The frame rate of the generated video.

SR string

The resolution tier of the generated video.

audio boolean

Indicates whether the generated video contains audio.

video_count integer

The number of generated videos. The value is fixed at 1.

request_id string

Unique request identifier for tracing and troubleshooting.

Task successful

{
    "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 by a window in a coffee shop, playing a soothing American country folk song on his guitar.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Task failed

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size does not match xxxxxx"
    }
}

Task query expired

The task_id is valid for 24 hours. After this period, queries return the following error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

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_name in 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 @kitten in the prompt to reference that entity. Note that you must leave a space after @kitten.
  • Example: @kitten and @puppy are playing on the grass.
Previous：PixVerse: Image-to-video from first and last framesNext：PixVerse - Video Lip Sync