Montage to Video API

The Montage to Video API generates video segments with a complete narrative structure from a story description, and supports passing in reference images as asset cues. In prompt, you can describe the narrative structure, scene changes, camera rhythm, and brand expression; provide visual direction references for products, people, or scenes via image_urls; and use the background music, sound effect, and narration parameters to control the audio layers. This endpoint is suited to producing short films with a beginning, development, and ending (such as brand films, product stories, event teasers, and social media ads), rather than single-action shots.

For the task status enum definitions, see API General Guide. To use local reference images, first obtain publicly accessible image URLs via Batch Uploads.

Create Task

Endpoint Information

• Protocol: HTTPS
• Endpoint: /videos/montage
• 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 that 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.

prompt

Type: string ｜ Required: Yes ｜ Default: None

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

• Length: 1 ~ 5,000 Chinese/English characters.
• We recommend describing the complete video rather than just a single frame, including the story theme, main scenes, camera rhythm, audio style, and ending goal.

image_urls

Type: array ｜ Required: No ｜ Default: None

List of reference image URLs, serving as asset cues to help the video maintain the visual direction of products, people, or scenes.

• Count: up to 20 images.
• Must be publicly accessible HTTP/HTTPS addresses.

resolution

Type: string ｜ Required: No ｜ Default: 720p

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

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.

duration

Type: int ｜ Required: No ｜ Default: 15

Duration of the generated video, in seconds (s). Enum values: 10, 15, 20, 25, 30, 45.

enable_bgm

Type: bool ｜ Required: No ｜ Default: true

Whether to generate background music. When true: background music generation is enabled When false: background music generation is disabled

enable_sfx

Type: bool ｜ Required: No ｜ Default: true

Whether to generate sound effects. When true: sound effect generation is enabled When false: sound effect generation is disabled

enable_narration

Type: bool ｜ Required: No ｜ Default: true

Whether to generate narration. When true: narration generation is enabled When false: narration generation is disabled

narration_language

Type: string ｜ Required: No ｜ Default: en

Narration language. Enum values: en (English), zh (Chinese).

• 【Note】Only takes effect when enable_narration is true.

narrator_preset

Type: string ｜ Required: No ｜ Default: auto

Narration style. Enum values: auto (automatic), warm_story (warm storytelling), clean_brand (clean brand), calm_documentary (calm documentary).

• 【Note】Only takes effect when enable_narration 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.

Request Example

curl --location --request POST '<BASE_URL>/videos/montage' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "bach-1.0",
    "prompt": "A brand film about a spring new-product launch, cherry blossoms in full bloom, camera slowly pushing from a park path to the product display stand, bright and warm overall",
    "image_urls": [
        "https://example.com/assets/product-front.jpg",
        "https://example.com/assets/product-scene.jpg"
    ],
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 15,
    "enable_bgm": true,
    "enable_sfx": true,
    "enable_narration": true,
    "narration_language": "zh",
    "narrator_preset": "warm_story",
    "enable_moderation": true
}'

Response Body

{
    "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/montage/{task_id}
• Method: GET
• Request Format: application/json
• Response Format: application/json

Request Headers

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

task_id

Type: string ｜ Required: Yes ｜ Default: None

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

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

Response Body

{
    "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": 1778313620,                           // Task processing start time, Unix timestamp, unit: seconds (s)
        "completed_at": 1778313800,                         // Task completion time, Unix timestamp, unit: seconds (s)
        "video_url": "https://example.com/result.mp4"       // Resource URL of the generated video
    },
    "timestamp": 1778313800                                 // 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.