Smart Split-Screen Layout

Compose 2-16 video clips into one split-screen video using the shared collage layout library. This endpoint performs layout and rendering only. It does not run face tracking, speaker detection, or person selection.

The same file_id may appear more than once in clips, with a different crop for each entry. This allows one source video to provide multiple simultaneous views.

Choosing a Layout Mode

Mode	Best For	Behavior
`auto`	Recommended default when the client does not maintain template IDs	Selects a reviewed template from the clip count, source aspects, and requested output ratio, then returns the effective `layout_id` and `random_seed`
`template`	Fixed designs and reproducing a previous task	Uses the specified `layout_id`; its slot count must match the number of clips

To lock an automatically selected result, first run with auto, save layout.layout_id, and use that ID in a later template request. random_seed reproduces spatial variants considered by auto mode. Changing clip count, crops, or output ratio may still change the selected layout even when the seed is unchanged.

layout_id Catalog

The catalog below covers 2-16 slots and shows the actual geometry for 1:1, 16:9, and 9:16 outputs. Select a ratio, then click any image to enlarge it and identify the required layout_id.

Choose an output ratio to inspect its layouts. Click any image to enlarge it.

Create Task

Basic Information

Item	Value
Method	`POST`
Path	`/task/video_split_screen`
Content-Type	`application/json`
Authentication	API Key passed directly in the `Authorization` header
Billing	Based on the shortest selected clip duration

Request Parameters

Parameter	Type	Required	Default	Description
`clips`	`array`	Yes	—	2-16 video clip entries
`layout_mode`	`string`	No	`auto`	`auto` selects a layout; `template` uses an explicit layout
`layout_id`	`integer`	Conditional	—	Required in template mode; slot count must equal the number of clips
`random_seed`	`integer`	No	Task-derived	0-2147483647; reproduces random spatial variants within a crop-equivalent layout group
`output_ratio`	`string`	No	`9:16`	`9:16`, `16:9`, or `1:1`
`quality`	`string`	No	`1080p`	`720p` or `1080p`
`fit_mode`	`string`	No	`cover`	`cover` fills and center-crops; `contain` preserves the full image with padding
`duration_mode`	`string`	No	`shortest`	V1 only supports `shortest`
`audio_mode`	`string`	No	`first`	`first`, `mix`, or `mute`
`gap_ratio`	`number`	No	`0.008`	Gap as a canvas ratio, from 0 to 0.05
`background_color`	`string`	No	`#000000`	Background color in `#RRGGBB` format

Output Dimensions

`output_ratio`	`720p`	`1080p`
`9:16`	`720 × 1280`	`1080 × 1920`
`16:9`	`1280 × 720`	`1920 × 1080`
`1:1`	`720 × 720`	`1080 × 1080`

Clip Entry

Field	Type	Required	Default	Description
`file_id`	`string`	Yes	—	Uploaded video file ID; it may be repeated in other entries
`begin_time_ms`	`integer`	No	`0`	Selected range start in milliseconds
`end_time_ms`	`integer`	No	Source end	Selected range end; zero or omitted means source end
`crop`	`object`	No	Full frame	Fixed normalized `{x,y,width,height}` crop inside `[0,1]`

crop is normalized against the source video: (0,0) is the top-left corner and (1,1) is the bottom-right corner. For example, the left half is {"x":0,"y":0,"width":0.5,"height":1}. This crop is applied before fit_mode; with cover, the service may crop further inside that region to fill the destination slot.

Audio Modes

Value	Behavior
`first`	Uses the first available audio stream in clip order; emits no audio if all clips are silent
`mix`	Mixes every available clip audio stream without extending the shortest output duration
`mute`	Emits a video without an audio stream

Example: Two Crops from One Source

curl -X POST https://api.ai-mcn.tv:10000/task/video_split_screen \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clips": [
      {
        "file_id": "537489015178246",
        "begin_time_ms": 0,
        "end_time_ms": 10000,
        "crop": {"x": 0, "y": 0, "width": 0.5, "height": 1}
      },
      {
        "file_id": "537489015178246",
        "begin_time_ms": 0,
        "end_time_ms": 10000,
        "crop": {"x": 0.5, "y": 0, "width": 0.5, "height": 1}
      }
    ],
    "layout_mode": "template",
    "layout_id": 21,
    "random_seed": 20260611,
    "output_ratio": "9:16",
    "quality": "1080p",
    "fit_mode": "cover",
    "audio_mode": "first"
  }'

Create Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "task_type": "video_split_screen",
    "status": "queued",
    "estimated_duration": 12,
    "estimated_queue_wait_duration": 0,
    "estimated_total_duration": 12
  }
}

Query Task

Item	Value
Method	`GET`
Path	`/task/video_split_screen/{task_id}`
Authentication	API Key passed directly in the `Authorization` header

output_result Fields

Field	Type	Description
`version`	`string`	Output schema version, currently `video_split_screen.v1`
`file_id`	`string`	Rendered video file ID
`download_url`	`string`	Rendered video download path
`duration_ms`	`integer`	Output duration, equal to the shortest selected range
`width` / `height`	`integer`	Output dimensions in pixels
`layout.layout_id`	`integer`	Exact selected template ID
`layout.equivalence_key`	`string`	Crop-equivalence group identifier shared by spatial variants with equal slot-size requirements
`layout.random_seed`	`integer`	Effective random seed, allowing the layout choice to be reproduced
`layout.slots`	`array`	Exact source-to-destination mappings ordered by destination slot

layout.slots Fields

Field	Type	Description
`slot_index`	`integer`	Zero-based template slot index
`clip_index`	`integer`	Index in the request `clips` array
`file_id`	`string`	Source video file ID
`begin_time_ms` / `end_time_ms`	`integer`	Effective selected source range
`source_crop`	`object`	Effective normalized source crop; `cover` may crop further inside the requested crop
`destination_rect`	`object`	Effective normalized destination rectangle after applying `gap_ratio`
`fit_mode`	`string`	Slot fit mode

Both source_crop and destination_rect contain x, y, width, and height:

source_crop is relative to the source video and identifies the region read from the original.
destination_rect is relative to the output canvas and identifies where that region appears.
Both use normalized 0-1 coordinates rather than pixels.
Use clip_index to map a slot back to the request, especially when the same file_id appears more than once.

Completed Result Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "version": "video_split_screen.v1",
      "file_id": "537489015178401",
      "download_url": "/download/c1/537489015178401.mp4",
      "duration_ms": 10000,
      "width": 1080,
      "height": 1920,
      "layout": {
        "layout_id": 21,
        "equivalence_key": "crop:0.5x1,0.5x1",
        "random_seed": 20260611,
        "slots": [
          {
            "slot_index": 0,
            "clip_index": 0,
            "file_id": "537489015178246",
            "begin_time_ms": 0,
            "end_time_ms": 10000,
            "source_crop": {"x": 0.171875, "y": 0, "width": 0.15625, "height": 1},
            "destination_rect": {"x": 0.003704, "y": 0.004167, "width": 0.490741, "height": 0.991667},
            "fit_mode": "cover"
          },
          {
            "slot_index": 1,
            "clip_index": 1,
            "file_id": "537489015178246",
            "begin_time_ms": 0,
            "end_time_ms": 10000,
            "source_crop": {"x": 0.671875, "y": 0, "width": 0.15625, "height": 1},
            "destination_rect": {"x": 0.503704, "y": 0.004167, "width": 0.490741, "height": 0.991667},
            "fit_mode": "cover"
          }
        ]
      }
    }
  }
}

Limits

A task uses one static layout and does not switch templates during playback.
V1 supports fixed crops only, not time-varying crop keyframes.
Output duration is always the shortest selected range; no looping, freezing, or padding is applied.
A task accepts up to 16 clips and also enforces a combined source-resolution decode limit.
gap_ratio creates inset space around each slot. Both that space and any contain padding use background_color.
This page provides a complete visual layout_id catalog. Continue to use layout_mode=auto when a fixed layout is unnecessary.
This endpoint does not identify faces or speakers. A higher-level workflow must provide clips and crops for person-driven layouts.

Error Codes

Error Code	HTTP Status	Description
`6013`	400	Required parameters such as `clips` are missing
`6016`	400	Invalid clip, crop, layout, or render parameter
`6004`	404	A referenced `file_id` does not exist
`6014`	400	An input is not a supported video type
`6502`	401	Authentication failed
`6201` / `6202`	402	Insufficient quota or balance