Layouts

A layout decides how a clip’s camera and screen layers are composed at a given time. Apply a layout to the whole clip (no startTimeMs/durationMs) or to a specific time range.

All times are milliseconds on the clip’s playback timeline — the video as watched, with cuts applied. It is the same timeline as get_transcript, thumbnails, and previews, so nothing needs converting. A start at or past the end of the clip is rejected with a 400.

Layout kinds

The layout field is an object discriminated by kind. Read the clip first to see its layoutSceneType — that determines which kinds are valid.

`kind`	Valid scene types	Variant fields
`fullscreen`	`cameraSubject`, `basicSubject`	`style: regular \| stretch` (camera-subject) or `screenFit: cover \| letterbox` (basic-subject)
`middle`	`cameraSubject`, `basicSubject`	`shape` (camera-subject)
`side-by-side`	`combi` (all ratios)	Landscape: `position: left \| right`, `style: regular \| even \| overlap`, `size` (when `style=overlap`). Portrait and square: `position: top \| bottom` (camera half), `style: even` only. `even` fills each half edge to edge and crops the screen to that half (no letterbox option); `regular` and `overlap` scale the whole screen to fit
`tv-presenter`	`combi` (landscape)	`position: left \| right`, `style: regular \| full \| overlap`
`camera-bubble`	`combi` (all ratios)	`position` (9-way), `shape: circle \| square \| landscape \| portrait`, `size: S \| M \| L`, optional `style: regular \| full`, optional `screenFit` (when `style=full`)
`camera-only`	`combi` (all ratios)	`style: fullscreen \| middle`, `punchIn` (when `style=fullscreen`), `shape` (when `style=middle`)
`screen-only`	`combi` (all ratios)	`style: fullscreen \| middle`, `screenFit` (when `style=fullscreen`)

list_saved_layouts

List your saved Favorite layouts. Each result includes an ID, name, scene type, and whether it is a preset or custom layout. Custom layouts also report the canvas ratio they require. Use the returned ID with apply_saved_layout.

apply_saved_layout

Apply one of your saved Favorite layouts to a clip. Omit the time range to set the clip-spanning base layout, or provide both startTimeMs and durationMs to apply it to part of the clip. Saved layouts must match the clip’s scene type. Custom layouts must also match the video’s canvas ratio.

string

required

Video ID

string

required

Clip ID

string

required

Saved layout ID from list_saved_layouts

integer

Start time in ms

integer

Duration in ms. Minimum 200ms.

list_layouts

List the layouts on a clip, including the synthetic base layout (the layout that spans the whole clip).

string

required

Video ID

string

required

Clip ID

add_layout

Add a layout to a clip. Pass startTimeMs + durationMs for a time range, or omit both for a clip-spanning layout. To add b-roll, give a time range and set media. You can omit layout and the server applies a full-frame b-roll layout suited to the clip (screen-only for combi clips, fullscreen for basic and camera-subject clips), or pass layout with a kind valid for the clip’s scene type — see Layout kinds.

string

required

Video ID

string

required

Clip ID

object

Structured layout — see Layout kinds. Omit it to apply the default full-frame b-roll layout for the clip’s scene type.

Show properties

string

required

One of the kinds valid for the clip’s scene type.

string

Sub-variant for fullscreen, side-by-side, tv-presenter, camera-bubble, camera-only, and screen-only.

string

left/right for landscape side-by-side and tv-presenter, top/bottom for portrait and square side-by-side, or one of nine positions for camera-bubble.

enum<string>

Camera size for camera-bubble and side-by-side with style: overlap — S, M, or L.

enum<string>

Camera shape for middle, camera-bubble, and camera-only with style: middle — circle, square, landscape, or portrait.

enum<string>

cover (default) or letterbox, for screen-only, basic-subject fullscreen, and camera-bubble with style: full.

boolean

Punch in on the camera for camera-only with style: fullscreen. Defaults to false.

integer

Start time in ms

integer

Duration in ms. Minimum 200ms.

enum<string>

Transition into the layout — spring or hardCut. Only valid on time-ranged layouts. When omitted, the user’s saved layout intro transition is used; the saved outro transition is applied when the following layout begins or resumes.

object

B-roll shown during the layout. Only valid on time-ranged layouts. One call fills one slot; to fill both, add one slot here and the other with update_layout.

Show properties

enum<string>

required

image or video.

string

required

Source ID from create_source (kind: "image" or kind: "video", matching type), uploaded first.

enum<string>

Which slot the media fills. screen (default) is the main subject frame and needs a layout that shows the screen — not camera-only. camera is a media bubble over the recording and needs a layout that renders the camera, such as camera-bubble, side-by-side, or tv-presenter. Pointing media at a slot the layout doesn’t show is rejected.

Example:

{
  "videoId": "vid_…",
  "clipId": "cl_…",
  "layout": {"kind": "side-by-side", "position": "left", "style": "regular"},
  "startTimeMs": 5000,
  "durationMs": 4000
}

update_layout

Update a layout on a clip. Only provided fields change.

string

required

Video ID

string

required

Clip ID

string

required

Layout ID (use base for the clip-spanning layout)

object

New structured layout

integer

New start time in ms

integer

New duration in ms. Minimum 200ms.

enum<string>

spring or hardCut. Rejected on the base layout.

object

Set the layout’s B-roll content for one slot. Rejected on the base layout. Same shape as add_layout’s media, including the optional slot field. Additive per slot: media in the other slot is preserved, and media already in the targeted slot is replaced.

Show properties

enum<string>

required

Media variant. One of image, video.

string

required

Source ID from create_source (kind: 'image' or kind: 'video', matching type).

enum<string>

Which slot the media fills: ‘screen’ (the subject/main frame, the default) or ‘camera’ (a media bubble over the recording behind it). ‘camera’ requires a layout that renders the camera (camera-bubble, side-by-side, tv-presenter). One of screen, camera.

remove_layout

Remove a non-base layout from a clip. Use update_layout to change the base layout.

string

required

Video ID

string

required

Clip ID

string

required

Layout ID

generate_auto_layouts

Let AI watch the clip and lay it out — the same as the editor’s “Auto layouts”. The AI picks an editing style (or follows style), sets the clip’s base layout, and adds time-ranged layout changes. Generation watches the actual video, so this can take on the order of a minute for longer clips.

This replaces the clip’s existing layouts with the generated ones.

string

required

Video ID

string

required

Clip ID

enum<string>

Editing style guiding the AI’s layout choices — one of product-demo-portrait, product-demo-round, product-demo-square, product-demo-wide, presentation-tv-show, presentation-portrait, tutorial-round, tutorial-square, intro, outro, intro-and-outro. Omit to let the AI pick one based on the clip’s content.

string

Free-form guidance for the AI, e.g. “keep the camera visible the whole time” or “punch in whenever a menu is opened”.

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Layout kinds

list_saved_layouts

apply_saved_layout

list_layouts

add_layout

update_layout

remove_layout

generate_auto_layouts

​Layout kinds

​list_saved_layouts

​apply_saved_layout

​list_layouts

​add_layout

​update_layout

​remove_layout

​generate_auto_layouts

Layout kinds

list_saved_layouts

apply_saved_layout

list_layouts

add_layout

update_layout

remove_layout

generate_auto_layouts