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` (`stretch` punches in to 1.15×; on basic-subject only for uploaded footage) 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 \| perspective`, `size` (when `style=overlap`); `perspective` angles camera and screen toward each other. 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`
`cut-out`	`combi`, `cameraSubject`	Combi: `position: left \| right`, optional `style: regular \| perspective` (landscape only) — the presenter is cut out of the camera feed (person matting) and blended over the screen; `perspective` fills most of the canvas with the screen, angled away toward the presenter in the bottom corner; portrait and square stories stack them (`right` = presenter on top). Camera-subject: no position; the presenter covers the frame over the story background
`camera-bubble`	`combi` (all ratios)	`position` (9-way), `size: S \| M \| L`, optional `shape: circle \| square \| landscape \| portrait` (defaults to `circle`, like the editor’s Camera Bubble picker), 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`)
`custom`	any	`subject` and `presentation` slot geometry — see Custom geometry

For landscape side-by-side layouts, match the editor’s picker labels to these fields:

Editor layout	`style`	`size`
Split Left / Split Right	`regular`	Not used
Split Left Overlap / Split Right Overlap	`overlap`	`M` or `L`
Split Left Small / Split Right Small	`overlap`	`S`
Split Left 50/50 / Split Right 50/50	`even`	Not used
Perspective Left / Perspective Right (Perspective switch on)	`perspective`	Not used

Use position: "left" or "right" for the camera’s side. If you mean an overlapping split (sometimes called “overlay”), choose overlap, not regular.

Camera style

Pass cameraStyle next to layout on add_layout or update_layout to override a named layout’s camera frame shape. The same field works in apply_video_edits layout operations and public API layout requests. You can update layoutId: "base" with cameraStyle alone, without sending layout.

Set none, circle, square, portrait, cutout, blob, or blob-outline.
cutout removes the camera background and frame, keeping the presenter in the named layout’s camera position. It switches pop-out off; sending cameraStyle: "cutout" together with a popOut object is rejected.
none uses a rectangle in the camera slot’s aspect ratio, rounded by the clip’s corners. For a squircle Pop-out frame, set cameraStyle: "none" and use update_clip to set corners: "squircle".
Send null to clear the override and use the named layout’s own shape. Omit the field to leave it unchanged.

Setting a camera style needs a camera recording and a named layout that frames the camera. Clips without a camera, cut-out, screen-only, and custom layouts reject a style value. For custom layouts, use the camera slot’s presentation.shape instead. Use layout.kind: "cut-out" for the dedicated cut-out layout, or cameraStyle: "cutout" to keep a named layout’s geometry. list_layouts, get_timeline, and layout responses report cameraStyle when an override is set; the field is absent when the layout’s own shape applies. Custom layouts report the shape in their geometry instead.

{
  "videoId": "vid_…",
  "clipId": "cl_…",
  "layoutId": "base",
  "cameraStyle": "circle",
  "popOut": {}
}

To place a frameless presenter in the bottom-left corner over a full-screen recording, use update_layout on a clip with both screen and camera recordings:

{
  "videoId": "vid_…",
  "clipId": "cl_…",
  "layoutId": "base",
  "layout": {
    "kind": "camera-bubble",
    "style": "full",
    "position": "bottom-left",
    "size": "L",
    "shape": "square"
  },
  "cameraStyle": "cutout"
}

On camera-bubble, shape still sets the camera slot the cut-out is drawn in, not a visible frame. Leave it out to use the default circle slot.

Custom geometry

kind: "custom" places each slot by hand, in artboard pixels (the video’s dimensions), like dragging layers in the editor. subject is the main layer — the screen recording on combi and basic-subject clips, the camera on camera-subject clips; presentation is the camera on combi clips. list_layouts reports custom layouts (including ones arranged in the editor) in the same shape, so read, tweak, write round-trips.

Field	Type	Meaning
`point`	`{x, y}`	Top-left corner in artboard pixels
`dimensions`	`{width, height}`	Size in artboard pixels. A screen keeps its recording’s aspect ratio: the box is fitted to it around the same centre
`shape`	`none` \| `circle` \| `square` \| `portrait` \| `cutout` \| `blob` \| `blob-outline`	Frame the layer is drawn in. `none` (default) is the plain rectangle; `circle`, `square` and `portrait` are the camera-bubble frames; `cutout` cuts the presenter out of the camera feed; `blob` is a wobbling bubble that grows toward the presenter’s hands, and `blob-outline` is the same with a white line around it
`corners`	`none` \| `regular` \| `squircle`	Corner rounding of a rectangular frame. Defaults to `regular`
`order`	integer	Stacking order; the lower one draws on top: 0 is the front layer and 1 the layer behind it (use only 0 and 1). Defaults to 0 for the subject, 1 for the presentation
`hidden`	boolean	Leave the layer out of the picture. Defaults to `false`

Writing over a layout that is already custom merges the fields you pass over its current geometry, so {"kind": "custom", "presentation": {"point": {"x": 1500, "y": 700}}} just moves the camera. Any other layout has no geometry to start from, so subject needs point and dimensions; if the clip has a camera and you leave presentation out, the camera is kept but hidden. Custom layouts can’t carry media. Use add_layout or update_layout for custom geometry, one call per layout; apply_video_edits accepts named layout kinds only.

{
  "videoId": "vid_…",
  "clipId": "cl_…",
  "layoutId": "base",
  "layout": {
    "kind": "custom",
    "subject": {"point": {"x": 80, "y": 60}, "dimensions": {"width": 1400, "height": 788}},
    "presentation": {"point": {"x": 1540, "y": 720}, "dimensions": {"width": 320, "height": 320}, "shape": "circle"}
  }
}

Pop-out

Any layout that frames the camera — camera-bubble, camera-only, side-by-side, tv-presenter, and camera-subject fullscreen / middle — can pop the presenter out of the frame: they are cut out of the camera feed and rise above a frame that sits behind their head. Pass popOut next to layout on add_layout and update_layout (and their batch_edit operations); list_layouts reports it on each layout. popOut: null switches it off, and switching a layout to cut-out or setting cameraStyle: "cutout" drops it, since a cut-out has no frame. The clip needs a camera recording. The Pop-out frame follows the camera style: circle draws a circle centred in the frame, with a diameter equal to its shorter side, even in a tall split panel. Blob styles draw an animated blob; other styles draw a rectangle rounded by the clip’s corners. Use Camera style to change the outline. Shadows and Snake borders follow the frame’s shape.

Field	Type	Default	Meaning
`background`	`original` \| `color`	`original`	What fills the frame behind the presenter: the camera feed, or `color`
`color`	`#RRGGBB` / `#RRGGBBAA`	`#6366F1`	Frame fill when `background` is `color`
`amount`	number, 0–0.5	`0.22`	How far the frame shrinks below the presenter, as a fraction of the camera slot
`outlineWidth`	number, 0–0.05	`0`	Outline around the frame as a fraction of its width; `0` draws none
`outlineColor`	`#RRGGBB` / `#RRGGBBAA`	`#FFFFFF`	Outline colour

Every field is optional: a write merges over the layout’s current settings, and a fresh pop-out takes the defaults for unset fields.

Crop

A layout can crop the clip’s screen recording for its own time range — the editor’s crop modal on “This layout only”. Pass crop next to layout on add_layout and update_layout as pixels of the recording removed from each edge: {"top": 0, "right": 420, "bottom": 0, "left": 420}. Other layouts keep following the clip’s crop; crop: null makes the layout follow it again. Masks that start in the layout stay anchored to the content they cover, and a custom layout’s screen box keeps its on-canvas scale unless the same request writes layout geometry. list_layouts reports each layout’s crop: its own crop, else the clip’s, absent when the recording is uncropped. The clip needs a screen recording or an uploaded video, and a clip with both crops the screen recording. To crop a screen recording across the whole clip use auto_crop.

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 and their geometry as a kind: custom layout. 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.

save_layout

Save a clip’s layout as a Favorite, like the editor’s star on a layout tile. Omit layoutId to save the clip-spanning base layout, or pass a layout ID from list_layouts. A named layout is saved by name and reapplies on any canvas. A custom layout — arranged in the editor or written with kind: custom (see Custom geometry) — is saved with its exact geometry and only reapplies to clips of the same scene type and canvas ratio. Saving a layout that is already a favorite returns the existing one.

string

required

Video ID

string

required

Clip ID

string

Layout ID from list_layouts. Defaults to base, the clip-spanning layout

string

Favorite name, as shown in the editor. Defaults to the layout’s display name

list_layouts

List the layouts on a clip, including the synthetic base layout (the layout that spans the whole clip). Custom layouts report their geometry as kind: custom. Named layouts report their camera frame override as cameraStyle when one is set — see Camera style. Each layout reports the crop of the clip’s screen recording it shows — see Crop. Every layout other than base reports followsBase: true when it follows the base layout, so updating base changes it too; false when it has its own layout.

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. To show a moment from the clip’s own recording as b-roll, such as a demo moment while the presenter keeps talking, set media to {"type": "recording", "startTimeMs": 42000}. It plays the clip’s screen recording from that point on the playback timeline, muted by default, with no copy, export or upload.

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, or custom.

object

custom only — the main layer’s geometry, see Custom geometry.

object

custom only — the camera’s geometry on combi clips.

string

Sub-variant for fullscreen, side-by-side, tv-presenter, camera-bubble, camera-only, screen-only, and landscape combi cut-out (regular or perspective).

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-subject clips), camera-bubble, and camera-only with style: middle — circle, square, landscape, or portrait. Other kinds reject it. Corner rounding and border style are set on the clip: see update_clip’s corners and borderStyle.

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. style: middle has no punch-in and rejects punchIn: true. 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, video, recording (the clip’s own screen recording, or its uploaded footage on an uploaded clip), or motion (a Tella Motion document of the video’s, played live).

string

Required for motion, and only used there: the Tella Motion document (ffd_…) from create_motion_document. A document of yours that no video plays yet moves to this video. A document that another overlay, b-roll or clip already plays returns 409; copy it with duplicate_motion_document and use the copy.

string

Source ID from create_source (kind: "image" or kind: "video", matching type), uploaded first. Required for image and video; not used with recording.

integer

Where the b-roll starts. Required for recording: a moment on this clip’s playback timeline; it then plays the recording on for the layout’s duration, including any footage cut out in that stretch. Optional for video (default 0): the in-point in the source itself, in ms of the source, like the editor’s Trim. It must be inside the source; a layout longer than what is left of the source loops from the in-point. Not used with image.

boolean

Silence the media’s own audio. Defaults to true for recording (its audio would repeat the clip’s) and false for video.

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.

object

Pop the presenter out of the camera frame — see Pop-out. Omitted or null leaves it off.

string | null

Override the named layout’s camera frame — none, circle, square, portrait, cutout, blob, or blob-outline. null clears the override; omitted leaves it unchanged. See Camera style for requirements.

object | null

Crop the clip’s screen recording for this layout only — see Crop. top, right, bottom, left in pixels of the recording; null follows the clip’s crop.

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). Updating base also changes every layout that reports followsBase: true, so there’s no need to update those one by one

object

New structured layout — a named kind, or custom geometry that merges over the layout’s current custom geometry (see Custom geometry)

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, recording.

string

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

integer

Where the b-roll starts: required for recording, on this clip’s playback timeline; optional for video, as the in-point in ms of the source itself. Not used with image.

boolean

Silence the media’s own audio. Defaults to true for recording and false for video.

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.

object | null

Switch the camera pop-out on (an object merges over the current settings — see Pop-out) or off (null). Omitted leaves it as it is, except that a cut-out layout or cameraStyle: "cutout" drops it. On the base layout this, cameraStyle, and crop are accepted without layout.

string | null

object | null

Crop the clip’s screen recording for this layout only — see Crop. top, right, bottom, left in pixels of the recording; null makes the layout follow the clip’s crop again. Omitted leaves it as it is.

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

Auto layouts

There is no tool that lays a clip out for you. To get the editor’s “Auto layouts” from your own agent, add the tella-auto-layouts skill (npx skills add tellahq/skills). It reads the clip’s transcript and frames, picks a base layout and adds timed layout changes with the tools on this page.

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Layout kinds

Camera style

Custom geometry

Pop-out

Crop

list_saved_layouts

apply_saved_layout

save_layout

list_layouts

add_layout

update_layout

remove_layout

Auto layouts

​Layout kinds

​Camera style

​Custom geometry

​Pop-out

​Crop

​list_saved_layouts

​apply_saved_layout

​save_layout

​list_layouts

​add_layout

​update_layout

​remove_layout

​Auto layouts

Layout kinds

Camera style

Custom geometry

Pop-out

Crop

list_saved_layouts

apply_saved_layout

save_layout

list_layouts

add_layout

update_layout

remove_layout

Auto layouts