curl --request POST \
  --url https://api.modellix.ai/api/v1/pixverse/v6-r2v \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_images": [
    {
      "url": "https://example.com/hero.png",
      "type": "subject",
      "ref_name": "hero"
    },
    {
      "url": "https://example.com/forest.png",
      "type": "background"
    }
  ],
  "prompt": "@hero runs across @forest under the northern lights",
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "16:9"
}
'

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-pixverse-r2v-001",
    "model_id": "pixverse/v6-r2v",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-pixverse-r2v-001"
    }
  }
}

{
  "code": 400,
  "message": "Invalid parameters: parameter 'image' is required"
}

{
  "code": 401,
  "message": "Authentication failed: invalid API key"
}

{
  "code": 429,
  "message": "Rate limit exceeded: 100 requests per minute, retry after 60 seconds"
}

{
  "code": 500,
  "message": "Internal server error"
}

V6 Reference-to-Video (Fusion)

[Core Function] PixVerse v6 reference-to-video (fusion) generates a video from a prompt while preserving subjects from 1-7 reference images; each reference can be tagged as subject/background and named for @-reference in the prompt. [Strengths] Precise multi-subject composition and identity preservation. [Best For] Putting specific characters/objects into a new scene, multi-character interactions. [Limitations] Do NOT use this for single-image animation (use Image-to-Video), two-frame transitions (use First-Last-Frame), or text-only generation (use Text-to-Video). It requires 1-7 reference images and a required aspect_ratio, and supports up to 1080p and a maximum of 15s. [Routing] Use when the user provides one or more reference images to be fused into the video, especially when distinguishing subject vs background or naming references for the prompt. The v6 and c1 reference-to-video variants accept identical parameters; choose the version the user requests.

POST

pixverse

v6-r2v

curl --request POST \
  --url https://api.modellix.ai/api/v1/pixverse/v6-r2v \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_images": [
    {
      "url": "https://example.com/hero.png",
      "type": "subject",
      "ref_name": "hero"
    },
    {
      "url": "https://example.com/forest.png",
      "type": "background"
    }
  ],
  "prompt": "@hero runs across @forest under the northern lights",
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "16:9"
}
'

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-pixverse-r2v-001",
    "model_id": "pixverse/v6-r2v",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-pixverse-r2v-001"
    }
  }
}

{
  "code": 400,
  "message": "Invalid parameters: parameter 'image' is required"
}

{
  "code": 401,
  "message": "Authentication failed: invalid API key"
}

{
  "code": 429,
  "message": "Rate limit exceeded: 100 requests per minute, retry after 60 seconds"
}

{
  "code": 500,
  "message": "Internal server error"
}

Authorizations

Authorization

string

header

required

API Key authentication. Format: Bearer YOUR_API_KEY.

Body

application/json

PixVerse reference-to-video (fusion) request. Fuses 1-7 reference images into a video; each reference image is an OBJECT carrying a url plus optional role (type) and a name (ref_name) referenceable in the prompt via @ref_name. NOTE: unlike xai/vidu (flat URL string arrays), PixVerse reference_images items are objects. Used by both v6 and c1 (the path determines the model version).

reference_images

object[]

required

Reference images (1-7) fused into the generated video. Each item is an object: a publicly accessible image URL, plus optional role (type: subject/background) and a name (ref_name) you can reference in the prompt via @ref_name for precise multi-subject control.

Required array length: 1 - 7 elements

Show child attributes

Example:

[
  {
    "url": "https://example.com/hero.png",
    "type": "subject",
    "ref_name": "hero"
  },
  {
    "url": "https://example.com/forest.png",
    "type": "background"
  }
]

prompt

string

required

Text prompt; may reference named images via @ref_name (e.g. "@hero in @forest").

Required string length: 1 - 5000

Example:

"@hero runs across @forest under the northern lights"

duration

integer

required

Video duration in seconds (required).

Required range: 1 <= x <= 15

Example:

5

quality

enum<string>

required

Output resolution (required).

Available options:

360p,

540p,

720p,

1080p

Example:

"720p"

aspect_ratio

enum<string>

required

Video aspect ratio (required).

Available options:

16:9,

9:16,

1:1,

3:4,

4:3,

2:3,

3:2,

21:9

Example:

"16:9"

seed

integer

Random seed (omit for random).

Required range: 0 <= x <= 2147483647

Example:

0

generate_audio_switch

boolean

default:false

Whether to generate audio.

Example:

false

Response

Task submitted successfully

code

integer

required

Response code, 0 indicates success

Example:

0

message

string

required

Response message

Example:

"success"

data

object

required

Detailed data about the submitted asynchronous task.

Show child attributes

V6 i2v V6 t2v