The Fusion(Reference to Video) feature allows you to quickly generate a video based on multiple reference images.
These reference images can include subjects and backgrounds, and you can use prompts to help compose them naturally into a coherent scene.
Fusion is suitable for various scenarios such as e-commerce, brand advertising, and narrative videos.

Prerequisites

Before you begin, make sure you have:

A valid PixVerse API key

A unique Ai-Trace-Id for each API request

An active subscription

The img_id(s) of the reference images you want to use in Fusion

step-step

Step 1. Prepare Your Image

Use high-quality and clear images. Higher resolution is recommended for better results.

For subject images, choose images where the main subject is clearly isolated and prominent.

For background images, select images with a clean and well-defined background.

Step 2. Prepare Your upload image API Request and uplaod image to get img_id

Construct your API request with the appropriate parameters:


curl --location --request POST 'https://app-api.pixverse.ai/openapi/v2/image/upload' \
--header 'API-KEY:your-api-key' \
--header 'Ai-trace-id: your-Ai-trace-id' \
--form 'image=@""'

Step 3. Prepare your Fusion(reference-to-video ) API

Parameter Details

Parameter Name	Required	Type	Description
image_references	Required	array	Array of reference images (1–3 items), including subjects and/or backgrounds
prompt	Required	string	To accurately describe the scene, use `@ref_name` in the prompt. 1. A space must follow `@ref_name`, e.g., `@cat plays` 2. The `@name` used in the prompt must exactly match the `ref_name` in `image_references`.
model	Required	string	Model version, supported in model v4.5 and above
duration	Required	int	Video duration in seconds, supported 5, 8
quality	Required	string	Video resolution
aspect_ratio	Required	string	Video aspect ratio
seed	Optional	int	Random seed (used for result reproduction)

Notes & Considerations:

image_references must be a non-empty array (1–3 items), and each item must be an object containing valid fields: "img_id", "ref_name", and "type".

"type" must be a valid value — please refer to the API documentation for supported options.

"ref_name" must be unique within the array.

The Fusion feature is only supported with model v4.5 and above.

In the prompt, when referencing a ref_name, you must:

Prefix it with @

Leave a space after it (e.g., @dog plays)

Ensure it exactly matches a ref_name defined in image_references.

Step 4.Handle the API Response

The API returns a JSON response with a video_id:
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": 0
}
}

Step 5.Check Generation Status

After creating the task, you will receive a video_id
Query periodically Get Video Generation Status API using this video_id
The status will change from 5 to 1 when processing is complete
{
"ErrCode": 0,
"ErrMsg": "string",
"Resp": {
"create_time": "string",
"id": 0,
"modify_time": "string",
"negative_prompt": "string",
"outputHeight": 0,
"outputWidth": 0,
"prompt": "string",
"resolution_ratio": 0,
"seed": 0,
"size": 0,
"status": 5,
"style": "string",
"url": "string"
}
}

Step 6. Download the Generated Video

You can access a generated video with "url"
{
"ErrCode": 0,
"ErrMsg": "string",
"Resp": {
"create_time": "string",
"id": 0,
"modify_time": "string",
"negative_prompt": "string",
"outputHeight": 0,
"outputWidth": 0,
"prompt": "string",
"resolution_ratio": 0,
"seed": 0,
"size": 0,
"status": 1,
"style": "string",
"url": "string"
}
}

Troubleshooting

Common issue

Your video is stuck in "Generating" status and hasn't completed after a long wait.

Please check if you're using the same AI-trace-ID for every request. This is the most common cause of this issue.

Status codes: 1: Generation successful; 5: Waiting for generation; 7: Content moderation failure; 8: Generation failed;

If you encounter status code 7, it means your generated video was filtered by our content moderation system. Please modify your parameters and try again. Any credits used for filtered videos will be automatically refunded to your account.

Common error codes

400/500 status : Incorrect code

400013 : Invalid binding request: incorrect parameter type or value

400017 : Invalid parameter

500044 : Reached the limit for concurrent generations.

How to use Fusion(Reference to video)?

Prerequisites#

step-step#

Step 1. Prepare Your Image#

Step 2. Prepare Your upload image API Request and uplaod image to get img_id#

Step 3. Prepare your Fusion(reference-to-video ) API#

Parameter Details#

Notes & Considerations:#

Step 4.Handle the API Response#

Step 5.Check Generation Status#

Step 6. Download the Generated Video#

Troubleshooting#

Common issue#

Common error codes#