> ## 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; use `update_text_overlay` to make them fade in and out.

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="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, or transition. 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="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>

`list_text_overlays` and `update_text_overlay` return the current `transition` 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>


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