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

# Overlays

> Place an image or video on top of a clip for a time range.

Place an image or video on top of a clip for a time range. Both reference a `sourceId` from `create_source` (`kind: "image"` or `kind: "video"` — upload the bytes first); the overlay type follows the source's kind.

* Position is a percentage `point`, so it survives aspect-ratio changes; size is a pixel `dimensions` box, so the shape never distorts.
* New overlays start with a hard cut. Use `update_overlay` to make them fade in and out.

For text, use [text overlays](/docs/mcp-tools/text-overlays).

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

List the image and video overlays on a clip.

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

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

## add\_overlay

Add an image or video overlay on top of a clip. Call `create_source` first (`kind: "image"` or `kind: "video"`), `PUT` the bytes, then pass the returned `sourceId` — the overlay type follows the source's kind. When `point`/`dimensions` are omitted, a centered box is computed from the source.

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

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

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

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

<ParamField path="sourceId" type="string" required>
  Source ID from `create_source`
</ParamField>

<ParamField path="name" type="string">
  Overlay name
</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">
  Overlay 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\_overlay

Update an existing overlay. Only provided fields change.

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

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

<ParamField path="overlayId" type="string" required>
  Overlay ID
</ParamField>

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

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

<ParamField path="name" type="string">
  Overlay name
</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 overlay in and out, while `hard_cut` makes it appear and disappear instantly.
</ParamField>

`list_overlays` and `update_overlay` return the current `transition` for every overlay.

## remove\_overlay

Remove an overlay from a clip.

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

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

<ParamField path="overlayId" type="string" required>
  Overlay ID
</ParamField>


## Related topics

- [Overlays overview](/docs/help/editing/overlays.md)
- [Text overlays](/docs/mcp-tools/text-overlays.md)
- [Update an overlay](/docs/api-reference/clips/update-an-overlay.md)
- [Remove an overlay](/docs/api-reference/clips/remove-an-overlay.md)
- [Add media overlays](/docs/help/editing/media-overlays.md)