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

# Text overlays

> Put titles, callouts, and labels on top of a clip.

Put text on top of a clip for a time range — a title, callout, lower third or label. Nothing needs uploading: pass the copy directly. Position uses a percentage `point` and a pixel `dimensions` box, exactly like image and video overlays, and `fontSize` is in the same artboard pixels as `dimensions` so text keeps its size relative to the frame.

Every styling field has a default taken from the editor, so `text`, `startTimeMs` and `durationMs` are usually all you need: Inter at 500 weight, white, center-aligned, no background, sized to 7.5% of the video's shorter side, in a centered box 60% of the artboard wide and 25% tall. New text overlays start with a hard cut and appear in front; use `update_text_overlay` to change their transition or place them behind a cut-out presenter.

For a designed look, pass a `presetId` instead of styling by hand. [Text presets](#text-presets) are the tiles in the editor's Text panel — Tella's built-in styles (`default:title`, `default:caption`, `default:label`, …) and the ones the user saved — and a preset fills in the font, weight, width, color, size, alignment, background and background shape at once. Any of those fields sent alongside overrides the preset's value, the same as picking a tile and then tweaking it.

A weight or width outside the chosen font's own variable axis range is clamped when the video renders, the same way the editor clamps it.

`fontFamily` must be one of Tella's catalog fonts — the same list the editor's font picker offers, and the only families the renderer bundles: `Archivo`, `Barlow`, `Caveat`, `DM Sans`, `Figtree`, `Inter`, `Lora`, `Merriweather`, `Montserrat`, `Nunito Sans`, `Open Sans`, `Oswald`, `Playfair Display`, `Poppins`, `Raleway`, `Roboto`, `Roboto Flex`, `Roboto Mono`, `Source Sans 3`, `Space Grotesk`. Anything else is rejected with a `400` rather than silently rendering as Inter.

Reading is looser than writing: an overlay made before that catalog can report a different family it still renders with, so `list_text_overlays` may return a family you couldn't set. Updating such an overlay's text or timing works normally — the check only applies when you send `fontFamily` yourself.

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

## list\_text\_overlays

List the text overlays on a clip. Image and video overlays are listed separately by `list_overlays`.

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

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

## add\_text\_overlay

Add a text overlay on top of a clip.

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

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

<ParamField path="text" type="string" required>
  The text to display
</ParamField>

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

<ParamField path="durationMs" type="integer" required>
  Duration in ms
</ParamField>

<ParamField path="presetId" type="string">
  A preset from `list_text_presets` — `default:<id>` for a built-in style or a saved preset's ID. Supplies every style field below; fields sent alongside override it
</ParamField>

<ParamField path="fontFamily" type="enum<string>">
  One of the catalog fonts listed above. Defaults to Inter
</ParamField>

<ParamField path="fontSize" type="number">
  Font size in artboard pixels. Defaults to 7.5% of the video's shorter side
</ParamField>

<ParamField path="color" type="string">
  Hex color, `#RRGGBB` or `#RRGGBBAA`. Defaults to white
</ParamField>

<ParamField path="fontWeight" type="number">
  Variable-font weight axis — 100 (thin) to 900 (black). Defaults to 500
</ParamField>

<ParamField path="fontWidth" type="number">
  Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded. Defaults to 100
</ParamField>

<ParamField path="textAlign" type="enum<string>">
  Horizontal alignment inside the text box — `left`, `center`, or `right`. Defaults to `center`
</ParamField>

<ParamField path="background" type="object">
  Background behind the text, in the same object shape as a clip background — `{ type: "solid", color }`, with `color` as `#RRGGBB` or `#RRGGBBAA`. Defaults to transparent

  <Expandable title="properties">
    <ParamField path="type" type="enum<string>" required>
      Background variant. Text overlays take a solid background. One of `solid`.
    </ParamField>

    <ParamField path="color" type="string" required>
      Hex color string, #RRGGBB or #RRGGBBAA. Required when type = 'solid'.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="backgroundShape" type="enum<string>">
  Background shape — `none`, `regular`, or `squircle`. Defaults to `none`
</ParamField>

<ParamField path="point" type="object">
  Top-left corner — `{xPct, yPct}` (0-100), as a percentage of the video canvas

  <Expandable title="properties">
    <ParamField path="xPct" type="number" required>
      0-100
    </ParamField>

    <ParamField path="yPct" type="number" required>
      0-100
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="dimensions" type="object">
  Text box size in artboard pixels — `{width, height}`, both greater than 0

  <Expandable title="properties">
    <ParamField path="width" type="number" required>
      Width in artboard pixels, greater than 0
    </ParamField>

    <ParamField path="height" type="number" required>
      Height in artboard pixels, greater than 0
    </ParamField>
  </Expandable>
</ParamField>

## update\_text\_overlay

Update an existing text overlay — its copy, font, text color, background, timing, position, size, transition, or depth. Only provided fields change.

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

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

<ParamField path="textOverlayId" type="string" required>
  Text overlay ID
</ParamField>

<ParamField path="text" type="string">
  New text
</ParamField>

<ParamField path="presetId" type="string">
  Restyle the overlay with a preset from `list_text_presets`; its text, timing and placement stay. Style fields sent alongside override the preset's values
</ParamField>

<ParamField path="fontFamily" type="enum<string>">
  New font family, one of the catalog fonts listed above
</ParamField>

<ParamField path="fontSize" type="number">
  New font size in artboard pixels
</ParamField>

<ParamField path="color" type="string">
  New hex color, `#RRGGBB` or `#RRGGBBAA`
</ParamField>

<ParamField path="fontWeight" type="number">
  New weight — 100 (thin) to 900 (black)
</ParamField>

<ParamField path="fontWidth" type="number">
  New width axis, as a percentage
</ParamField>

<ParamField path="textAlign" type="enum<string>">
  New horizontal alignment inside the text box — `left`, `center`, or `right`
</ParamField>

<ParamField path="background" type="object">
  New background behind the text — `{ type: "solid", color }`, with `color` as `#RRGGBB` or `#RRGGBBAA`

  <Expandable title="properties">
    <ParamField path="type" type="enum<string>" required>
      Background variant. Text overlays take a solid background. One of `solid`.
    </ParamField>

    <ParamField path="color" type="string" required>
      Hex color string, #RRGGBB or #RRGGBBAA. Required when type = 'solid'.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="backgroundShape" type="enum<string>">
  New background shape — `none`, `regular`, or `squircle`
</ParamField>

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

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

<ParamField path="point" type="object">
  New top-left — `{xPct, yPct}` (0-100)

  <Expandable title="properties">
    <ParamField path="xPct" type="number" required>
      0-100
    </ParamField>

    <ParamField path="yPct" type="number" required>
      0-100
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="dimensions" type="object">
  New size in artboard pixels — `{width, height}`, both greater than 0

  <Expandable title="properties">
    <ParamField path="width" type="number" required>
      Width in artboard pixels, greater than 0
    </ParamField>

    <ParamField path="height" type="number" required>
      Height in artboard pixels, greater than 0
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="transition" type="enum<string>">
  Intro and outro animation — `smooth` fades the text in and out, while `hard_cut` makes it appear and disappear instantly.
</ParamField>

<ParamField path="depth" type="enum<string>">
  `front` paints the text over everything. `behind_presenter` places it behind the cut-out presenter but above the clip background and screen. Without a camera in the layout, the text stays in front.
</ParamField>

`list_text_overlays` and `update_text_overlay` return the current `transition` and `depth` for every text overlay.

## remove\_text\_overlay

Remove a text overlay from a clip.

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

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

<ParamField path="textOverlayId" type="string" required>
  Text overlay ID
</ParamField>

## Text presets

A text preset is everything about a text overlay except its text, timing and placement. Its `style` carries `fontFamily`, `fontWeight`, `fontWidth`, `color`, `textAlign`, `background`, `backgroundShape` and a `fontSizeScale` — the size relative to the editor's default (7.5% of the canvas's shorter side), so the same preset reads the same on every canvas. Adding an overlay with a preset resolves that scale to artboard pixels for the video it lands on.

### list\_text\_presets

List Tella's built-in text styles and the presets saved by the authenticated user. Each result has a `presetId`, `name`, `scope` (`default` or `personal`) and its `style`.

Pass a returned `presetId` to `add_text_overlay`, `update_text_overlay`, or the same operations in `apply_video_edits`.

### save\_text\_preset

Save a personal text preset, like the editor's "Save style" on a text overlay. The style starts from an existing text overlay when `videoId` and `textOverlayId` are given — which keeps a custom font and reads the size relative to that video's canvas — else from the editor's default text look. Every style field passed alongside overrides it. The preset then shows up in `list_text_presets` and in the editor's Text panel for the same user.

<ParamField path="name" type="string" required>
  Preset name, as shown in the editor
</ParamField>

<ParamField path="videoId" type="string">
  Video holding the text overlay to copy the style from. Goes together with `textOverlayId`
</ParamField>

<ParamField path="textOverlayId" type="string">
  Text overlay to copy the style from. Goes together with `videoId`
</ParamField>

<ParamField path="fontFamily" type="enum<string>">
  One of the catalog fonts listed above
</ParamField>

<ParamField path="fontWeight" type="number">
  Variable-font weight axis — 100 (thin) to 900 (black)
</ParamField>

<ParamField path="fontWidth" type="number">
  Variable-font width axis, as a percentage — 100 is normal
</ParamField>

<ParamField path="color" type="string">
  Hex color, `#RRGGBB` or `#RRGGBBAA`
</ParamField>

<ParamField path="fontSizeScale" type="number">
  Font size relative to the editor's default: 1 is the default, 0.6 a caption, 1.4 a headline. Defaults to 1, or to the copied overlay's size
</ParamField>

<ParamField path="textAlign" type="enum<string>">
  `left`, `center`, or `right`
</ParamField>

<ParamField path="background" type="object">
  Background behind the text — `{ type: "solid", color }`
</ParamField>

<ParamField path="backgroundShape" type="enum<string>">
  `none`, `regular`, or `squircle`
</ParamField>

### delete\_text\_preset

Delete one of the authenticated user's saved text presets. Built-in `default:` presets can't be deleted, and text overlays already styled with the preset keep their look.

<ParamField path="presetId" type="string" required>
  A `personal` preset ID from `list_text_presets`
</ParamField>


## Related topics

- [Overlays](/docs/mcp-tools/overlays.md)
- [Update a text overlay](/docs/api-reference/clips/update-a-text-overlay.md)
- [Remove a text overlay](/docs/api-reference/clips/remove-a-text-overlay.md)
- [List text overlays on a clip](/docs/api-reference/clips/list-text-overlays-on-a-clip.md)
- [Add a text overlay to a clip](/docs/api-reference/clips/add-a-text-overlay-to-a-clip.md)