> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Layouts

> Compose a clip's camera and screen layers, add B-roll, and let AI lay out a clip.

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.

<Note>
  **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`.
</Note>

### 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.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="savedLayoutId" type="string" required>
  Saved layout ID from `list_saved_layouts`
</ParamField>

<ParamField path="startTimeMs" type="integer">
  Start time in ms
</ParamField>

<ParamField path="durationMs" type="integer">
  Duration in ms. Minimum 200ms.
</ParamField>

## list\_layouts

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

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

## 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](#layout-kinds).

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="layout" type="object">
  Structured layout — see [Layout kinds](#layout-kinds). Omit it to apply the default full-frame b-roll layout for the clip's scene type.

  <Expandable title="properties">
    <ParamField path="kind" type="string" required>
      One of the kinds valid for the clip's scene type.
    </ParamField>

    <ParamField path="style" type="string">
      Sub-variant for `fullscreen`, `side-by-side`, `tv-presenter`, `camera-bubble`, `camera-only`, and `screen-only`.
    </ParamField>

    <ParamField path="position" type="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`.
    </ParamField>

    <ParamField path="size" type="enum<string>">
      Camera size for `camera-bubble` and `side-by-side` with `style: overlap` — `S`, `M`, or `L`.
    </ParamField>

    <ParamField path="shape" type="enum<string>">
      Camera shape for `middle`, `camera-bubble`, and `camera-only` with `style: middle` — `circle`, `square`, `landscape`, or `portrait`.
    </ParamField>

    <ParamField path="screenFit" type="enum<string>">
      `cover` (default) or `letterbox`, for `screen-only`, basic-subject `fullscreen`, and `camera-bubble` with `style: full`.
    </ParamField>

    <ParamField path="punchIn" type="boolean">
      Punch in on the camera for `camera-only` with `style: fullscreen`. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="startTimeMs" type="integer">
  Start time in ms
</ParamField>

<ParamField path="durationMs" type="integer">
  Duration in ms. Minimum 200ms.
</ParamField>

<ParamField path="transitionStyle" type="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.
</ParamField>

<ParamField path="media" type="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`.

  <Expandable title="properties">
    <ParamField path="type" type="enum<string>" required>
      `image` or `video`.
    </ParamField>

    <ParamField path="sourceId" type="string" required>
      Source ID from `create_source` (`kind: "image"` or `kind: "video"`, matching `type`), uploaded first.
    </ParamField>

    <ParamField path="slot" type="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.
    </ParamField>
  </Expandable>
</ParamField>

Example:

```json theme={null}
{
  "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.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="layoutId" type="string" required>
  Layout ID (use `base` for the clip-spanning layout)
</ParamField>

<ParamField path="layout" type="object">
  New structured layout
</ParamField>

<ParamField path="startTimeMs" type="integer">
  New start time in ms
</ParamField>

<ParamField path="durationMs" type="integer">
  New duration in ms. Minimum 200ms.
</ParamField>

<ParamField path="transitionStyle" type="enum<string>">
  `spring` or `hardCut`. Rejected on the base layout.
</ParamField>

<ParamField path="media" type="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.

  <Expandable title="properties">
    <ParamField path="type" type="enum<string>" required>
      Media variant. One of `image`, `video`.
    </ParamField>

    <ParamField path="sourceId" type="string" required>
      Source ID from `create_source` (`kind: 'image'` or `kind: 'video'`, matching `type`).
    </ParamField>

    <ParamField path="slot" 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`.
    </ParamField>
  </Expandable>
</ParamField>

## remove\_layout

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

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="layoutId" type="string" required>
  Layout ID
</ParamField>

## 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.

<Warning>
  This replaces the clip's existing layouts with the generated ones.
</Warning>

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="style" type="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.
</ParamField>

<ParamField path="instructions" type="string">
  Free-form guidance for the AI, e.g. "keep the camera visible the whole time" or "punch in whenever a menu is opened".
</ParamField>


## Related topics

- [Layouts](/docs/help/editing/use-layouts.md)
- [Custom layouts](/docs/help/editing/custom-layouts.md)
- [Auto layouts](/docs/help/editing/use-auto-layouts.md)
- [Update a layout](/docs/api-reference/clips/update-a-layout.md)
- [Multiple layouts](/docs/help/editing/use-multi-layouts.md)