Montage Video API

Description

The Montage Video API generates a more complete video segment from a story description, with support for reference images as asset cues. Use prompt to describe the narrative structure, scene changes, camera pacing, and brand expression, and use the background music, sound effect, and narration parameters to control the audio layers. This endpoint is designed for producing short films with a beginning, development, and ending — rather than a single-action shot.

Use Cases

• Generate brand films, product stories, event teasers, and social media ads.
• Organize multi-shot video content based on a copy script.
• Use reference images to keep the video aligned with the visual direction of products, characters, or scenes.

Endpoint Information

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

Create Task

Request Parameters

Constraints: prompt is required; duration supports 10-45 seconds; image_urls supports up to 20 images.

Request Example

curl -X POST '<BASE_URL>/videos/montage' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "prompt": "A brand film about a spring product launch. Cherry blossoms in full bloom; the camera slowly pushes in from a park path to the product display stand. Overall bright and warm tone.",
    "image_urls": [
      "https://example.com/assets/product-front.jpg",
      "https://example.com/assets/product-scene.jpg"
    ],
    "duration": 15,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "enable_bgm": true,
    "enable_sfx": true,
    "enable_narration": true,
    "narration_language": "en",
    "narrator_preset": "warm_story"
  }'

Success Response

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

Query Task

Path Parameters

Request Example

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

Success Response

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

Notes

• prompt should describe the complete video, not just a single frame. We recommend including the story theme, main scenes, camera pacing, audio style, and the intended ending.
• image_urls are reference assets; when omitted, the system generates purely from prompt. We recommend using Batch Upload first to obtain stable, accessible image URLs.
• When enable_narration=false, narration_language and narrator_preset have no effect.
• 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.

Related Documents

• API Basics
• Capability Map
• Batch Upload
• Using Callbacks
• Error Handling