Elements to Video

Elements to Video API

Description

The Elements to Video API composes multiple visual elements into a single video. You can pass plain images, or pass subject inputs carrying subject metadata, allowing the model to jointly reference characters, objects, scenes, and action descriptions during generation. This endpoint is designed for creative video generation where multiple assets participate in the composition and subject consistency must be preserved.

Use Cases

Combine multiple assets — characters, products, backgrounds, props — into a single video.
Define the same character or object with multiple images to improve subject consistency.
Generate multi-element videos for ads, IP characters, storyboards, and product scenes.

Endpoint Information

Item	Description
Create task	`POST /videos/elements2video`
Query task	`GET /videos/elements2video/{task_id}`
Authentication	Bearer Token

The full request URL consists of the base URL and the endpoint path; see API Basics.

Create Task

Request Parameters

Parameter	Type	Required	Default	Description
`reference_inputs`	array	Yes	-	List of reference inputs, up to 9 elements; supports two types: `image` and `subject`
`prompt`	string	Yes	-	Video content description, up to 10,000 characters
`negative_prompt`	string	No	-	Content you do not want to appear in the video, up to 10,000 characters
`resolution`	string	Yes	-	Output resolution. Allowed values: `720p`, `1080p`
`duration`	integer	No	`6`	Video duration, range `1-6` seconds
`aspect_ratio`	string	No	`16:9`	Aspect ratio. Allowed values: `16:9`, `9:16`, `1:1`
`fps`	integer	No	`24`	Video frame rate. Allowed values: `24`, `30`
`generate_audio`	boolean	No	`false`	Whether to generate audio
`audio_prompt`	string	No	-	Audio description, up to 200 characters; only effective when `generate_audio=true`
`callback_url`	string	No	-	Callback URL invoked when the task completes; must be an HTTP/HTTPS URL, up to 500 characters
`seed`	integer	No	-	Random seed, range `0-10000000`; if omitted, handled by the system

Constraints: reference_inputs supports up to 9 elements; resolution is required; duration supports 1-6 seconds; fps only supports 24 and 30.

`reference_inputs` Structure

Image Input

Provides a single image asset.

json

Copy

{
  "type": "image",
  "url": "https://example.com/background.jpg"
}

Parameter	Type	Required	Description
`type`	string	Yes	Fixed value: `image`
`url`	string	Yes	Image URL

Subject Input

Defines a character or object that must remain consistent. Each subject input requires 2-4 images plus the subject metadata.

json

Copy

{
  "type": "subject",
  "images": [
    "https://example.com/hero-front.jpg",
    "https://example.com/hero-side.jpg"
  ],
  "subject": {
    "subject_name": "Hero Character",
    "subject_desc": "A warrior wearing golden armor",
    "subject_style": "realistic",
    "subject_type": "character"
  }
}

Parameter	Type	Required	Default	Description
`type`	string	Yes	-	Fixed value: `subject`
`images`	string[]	Yes	-	Image URLs of the same subject, `2-4` images
`subject.subject_name`	string	Yes	-	Subject name, up to 50 characters
`subject.subject_desc`	string	No	-	Subject description, up to 500 characters
`subject.subject_style`	string	No	`realistic`	Subject style. Allowed values: `realistic`, `anime`, `cartoon`, `3d`, `pixel`
`subject.subject_type`	string	No	`character`	Subject type. Allowed values: `character`, `object`

Request Example

bash

Copy

curl -X POST '<BASE_URL>/videos/elements2video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "reference_inputs": [
      {
        "type": "subject",
        "images": [
          "https://example.com/hero-front.jpg",
          "https://example.com/hero-side.jpg"
        ],
        "subject": {
          "subject_name": "Hero Character",
          "subject_desc": "A warrior wearing golden armor",
          "subject_style": "realistic",
          "subject_type": "character"
        }
      },
      {
        "type": "image",
        "url": "https://example.com/castle-background.jpg"
      }
    ],
    "prompt": "The hero walks toward the castle, sunlight glinting on the armor, camera slowly pushing in, epic overall tone",
    "negative_prompt": "blurry, low quality, distorted frames",
    "resolution": "1080p",
    "duration": 6,
    "aspect_ratio": "16:9",
    "fps": 24,
    "generate_audio": false
  }'

Success Response

json

Copy

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": 1778313600,
    "status": "TASK_PENDING"
  },
  "timestamp": 1778313600
}

Field	Type	Description
`task_id`	string	Task ID, used to query the result
`created_at`	number	Task creation time, Unix timestamp in seconds
`status`	string	Task status; see Task Status

Query Task

Path Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	Task ID returned by the create-task endpoint

Request Example

bash

Copy

curl -X GET '<BASE_URL>/videos/elements2video/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <API_TOKEN>'

Success Response

json

Copy

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_SUCCEEDED",
    "created_at": 1778313600,
    "started_at": 1778313610,
    "completed_at": 1778313700,
    "video_url": "https://example.com/result.mp4"
  },
  "timestamp": 1778313700
}

Field	Type	Description
`task_id`	string	Task ID
`status`	string	Task status; see Task Status
`created_at`	number	Task creation time, Unix timestamp in seconds
`started_at`	number	Time the task started processing, Unix timestamp in seconds
`completed_at`	number	Task completion time, Unix timestamp in seconds
`video_url`	string	Generated video URL

Notes

We recommend using Batch Upload first to obtain stable, accessible URLs for image assets.
reference_inputs supports a total of at most 9 items; for subject-type inputs, images must contain 2-4 images of the same subject.
prompt should describe the relationships between elements, the subject's actions, the scene, and the camera work — avoid simply listing asset names.
If you need a task completion notification, pass a callback_url — see Using Callbacks for the callback protocol; otherwise, retrieve the task status via the query endpoint.

Image to Video

Montage to Video

On this page

Elements to Video

Elements to Video API

Description

Use Cases

Endpoint Information

Create Task

Request Parameters

reference_inputs Structure

Image Input

Subject Input

Request Example

Success Response

Query Task

Path Parameters

Request Example

Success Response

Notes

Related Documents

`reference_inputs` Structure