Reference to Video

Reference to Video API

The Reference to Video API combines multiple visual elements into a single video. You can pass in regular images (image type) or subject inputs carrying subject information (subject type), letting the model reference characters, objects, scenes, and action descriptions at generation time. The model independently locks and preserves each subject's features, making it suitable for creative video generation where multiple assets jointly compose the frame and subject consistency must be maintained — for example, ads, IP characters, story storyboards, and product scenes.

For the task status enum definitions, see API General Guide. We recommend first obtaining publicly accessible image URLs for your image assets via Batch Uploads.

Create Task

Endpoint Information

Protocol: HTTPS
Endpoint: /videos/reference2video
Method: POST
Request Format: application/json
Response Format: application/json

The full request URL is formed by concatenating the base URL and the endpoint path; see API General Guide.

Request Headers

`Content-Type`

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

Fixed value: application/json

`Authorization`

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

Format: Bearer <API_TOKEN>
【Note】There is exactly one space between Bearer and <API_TOKEN>.

Request Body

`model_name`

Type: string ｜ Required: No ｜ Default: bach-1.0

Model name. Enum values: bach-1.0.

`reference_inputs`

Type: array ｜ Required: Yes ｜ Default: None

Reference input list, containing the image and subject elements that participate in composing the frame.

Supports two types — image (image input) and subject (subject input) — which can be mixed in one request.
【Note】Currently supports up to 9 elements. For the structure definition, see reference_inputs Structure below.
For the subject type, images must provide 2 ~ 4 images of the same subject; we recommend covering different viewing angles to improve subject consistency.

`prompt`

Type: string ｜ Required: Yes ｜ Default: None

Positive text prompt, i.e., the video content description.

Must not exceed 10,000 Chinese/English characters.
We recommend describing the relationships between elements, subject actions, scene, and camera; we do not recommend merely listing asset names.

`resolution`

Type: string ｜ Required: Yes ｜ Default: None

Resolution of the generated video. Enum values: 720p, 1080p.

`duration`

Type: int ｜ Required: No ｜ Default: 6

Duration of the generated video, in seconds (s). Value range: 1 ~ 8.

`aspect_ratio`

Type: string ｜ Required: No ｜ Default: 16:9

Frame aspect ratio (width:height) of the generated video. Enum values: 16:9, 9:16, 1:1.

`generate_audio`

Type: bool ｜ Required: No ｜ Default: false

Whether to generate audio along with the video. When true: synchronized audio generation is enabled When false: synchronized audio generation is disabled

`audio_prompt`

Type: string ｜ Required: No ｜ Default: None

Audio content description.

Must not exceed 200 characters.
【Note】Only takes effect when generate_audio is true.

`enable_moderation`

Type: bool ｜ Required: No ｜ Default: true

Whether to enable content moderation. When true: content moderation is enabled When false: content moderation is disabled

【Note】enable_moderation only takes effect after being configured by an administrator. Please contact your administrator if needed.

`callback_url`

Type: string ｜ Required: No ｜ Default: Empty

Callback notification URL for this task's result

Must be a valid HTTP/HTTPS URL
Must not exceed 500 characters.
If configured, the server will proactively send notifications when the task status changes; for the notification message schema, see Using Callbacks.

`reference_inputs` Structure

reference_inputs is an array of objects; each element declares its input type via the type field, and the two types can be mixed in the same request.

Image input (`type: "image"`)

Used to provide a single image asset, such as a background, prop, or scene reference.

json

Copy

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

`type`

Type: string ｜ Required: Yes ｜ Default: None

Input type.

Fixed as image.

`url`

Type: string ｜ Required: Yes ｜ Default: None

Image URL.

Must be a publicly accessible HTTP/HTTPS address.

Subject input (`type: "subject"`)

Used to define a character or object that must remain consistent across shots. Each subject input must provide 2 ~ 4 images of the same subject (we recommend covering different viewing angles), and fill in subject information to give the model richer references.

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

`type`

Type: string ｜ Required: Yes ｜ Default: None

Input type.

Fixed as subject.

`images`

Type: string[] ｜ Required: Yes ｜ Default: None

List of image URLs of the same subject.

Count: 2 ~ 4 images.
Must be publicly accessible HTTP/HTTPS addresses.

`subject.subject_name`

Type: string ｜ Required: Yes ｜ Default: None

Subject name.

Must not exceed 50 characters.

`subject.subject_desc`

Type: string ｜ Required: No ｜ Default: Empty

Subject description.

Must not exceed 500 characters.

`subject.subject_style`

Type: string ｜ Required: No ｜ Default: realistic

Subject style. Enum values: realistic, anime, cartoon, 3d, pixel.

`subject.subject_type`

Type: string ｜ Required: No ｜ Default: character

Subject type. Enum values: character (character), object (object).

Request Example

The following example combines one subject input (to maintain character consistency) with one background image:

bash

Copy

curl --location --request POST '<BASE_URL>/videos/reference2video' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "bach-1.0",
    "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 off the armor, camera slowly pushing in, an overall epic feel",    
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,    
    "generate_audio": false
}'

Response Body

json

Copy

{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000", // Task ID, generated by the system, used to query the task result later
        "status": "TASK_PENDING",                          // Task status; for enum values see "API General Guide - Task Status"
        "created_at": 1778313600                           // Task creation time, Unix timestamp, unit: seconds (s)
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp, unit: seconds (s)
}

`task_id`

Type: string

Task ID, generated by the system.

【Note】Please store it safely; it is used to query the task result.

`status`

Type: string

Task status; for enum values see Task Status.

`created_at`

Type: number

Task creation time, Unix timestamp, unit: seconds (s).

Query Task (Single)

Endpoint Information

Protocol: HTTPS
Endpoint: /videos/reference2video/{task_id}
Method: GET
Request Format: application/json
Response Format: application/json

Request Headers

`Content-Type`

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

Fixed value: application/json

`Authorization`

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

Format: Bearer <API_TOKEN>
【Note】There is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

`task_id`

Type: string ｜ Required: Yes ｜ Default: None

The Reference to Video task ID.

【Note】This is a path parameter; fill the value directly into the request path. Its value is the task_id returned by the create-task endpoint.

Request Example

bash

Copy

curl --location --request GET '<BASE_URL>/videos/reference2video/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer <API_TOKEN>'

Response Body

json

Copy

{
    "code": 200,                                           // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",  // Task ID, generated by the system
        "status": "TASK_SUCCEEDED",                         // Task status; for enum values see "API General Guide - Task Status"
        "created_at": 1778313600,                           // Task creation time, Unix timestamp, unit: seconds (s)
        "started_at": 1778313610,                           // Task processing start time, Unix timestamp, unit: seconds (s)
        "completed_at": 1778313700,                         // Task completion time, Unix timestamp, unit: seconds (s)
        "video_url": "https://example.com/result.mp4"       // Resource URL of the generated video
    },
    "timestamp": 1778313700                                 // Response time, Unix timestamp, unit: seconds (s)
}

`task_id`

Type: string

Task ID, generated by the system.

`status`

Type: string

Task status; for enum values see Task Status.

`created_at`

Type: number

Task creation time, Unix timestamp, unit: seconds (s).

`started_at`

Type: number

Task processing start time, Unix timestamp, unit: seconds (s).

`completed_at`

Type: number

Task completion time, Unix timestamp, unit: seconds (s).

`video_url`

Type: string

Resource URL of the generated video.

【Note】For data security, we recommend transferring and storing the generated video promptly.
Please poll the task status via the query endpoint until you obtain video_url or confirm the task has failed.

Montage

Text to Image

On this page

Reference to Video

Reference to Video API

Create Task

Endpoint Information

Request Headers

Content-Type

Authorization

Request Body

model_name

reference_inputs

prompt

resolution

duration

aspect_ratio

generate_audio

audio_prompt

enable_moderation

callback_url

reference_inputs Structure

Image input (type: "image")

type

url

Subject input (type: "subject")

type

images

subject.subject_name

subject.subject_desc

subject.subject_style

subject.subject_type

Request Example

Response Body

task_id

status

created_at

Query Task (Single)

Endpoint Information

Request Headers

Content-Type

Authorization

Path Parameters

task_id

Request Example

Response Body

task_id

status

created_at

started_at

completed_at

video_url

`Content-Type`

`Authorization`

`model_name`

`reference_inputs`

`prompt`

`resolution`

`duration`

`aspect_ratio`

`generate_audio`

`audio_prompt`

`enable_moderation`

`callback_url`

`reference_inputs` Structure

Image input (`type: "image"`)

`type`

`url`

Subject input (`type: "subject"`)

`type`

`images`

`subject.subject_name`

`subject.subject_desc`

`subject.subject_style`

`subject.subject_type`

`task_id`

`status`

`created_at`

`Content-Type`

`Authorization`

`task_id`

`task_id`

`status`

`created_at`

`started_at`

`completed_at`

`video_url`