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

# Shape overlays

> Put squares, circles, stars, arrows, and custom SVG paths on top of a clip.

Put a shape on top of a clip for a time range: `square`, `circle`, `triangle`, `diamond`, `star`, `hexagon`, `arrow`, or a custom `path`. A shape stretches to fill its box, so a non-square `dimensions` makes a rectangle or an oval. Position uses a percentage `point` and a pixel `dimensions` box, exactly like [image and video overlays](https://www.tella.com/docs/mcp-tools/overlays.md).

The fill takes the same object as a clip background (`solid`, `gradient`, `image`, `video`, or `shaderGradient`; `ambient` is rejected), cut to the shape's outline. A solid `#00000000` fill leaves only the border. With no style fields, a new shape is a centered square in Tella purple, a third of the artboard's longer side, with no border or shadow.

Shape overlays share the stacking order, `depth`, and [animation](https://www.tella.com/docs/mcp-tools/overlays.md#animate-overlays) options of image and video overlays. Their timing follows the footage like text overlays: cutting out footage under a shape shortens it.

> [!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`.

## Custom paths

Send `path` with SVG path data (`d`) in a 0–100 box to draw your own outline; sending it makes the shape a `path`. The path stretches with the overlay box like any other shape.

* Closed subpaths (ending in `Z`) are filled. An open path, such as a line or curve, shows only its `border`, drawn centered on the line with round joins and caps.
* Absolute and relative commands, implicit repeats, and arcs are supported. Paths are capped at 10,000 characters, and a path that doesn't parse is rejected with a `400`.
* An arc's radii stretch with the box but its rotation doesn't, so a rotated arc in a non-square box is approximate.

```json theme={"system"}
{"path": "M50 0 L100 100 L0 100 Z", "fill": {"type": "solid", "color": "#FF6B00"}}
```

## list\_shape\_overlays

List the shape overlays on a clip. Each result includes its `id`, `shapeType`, `path` (or `null`), `fill`, `corners`, `border`, `shadow`, timing, `point`, `dimensions`, `transition`, `depth`, and `zIndex`.

**videoId** `string` *required*

Video ID

**clipId** `string` *required*

Clip ID

## add\_shape\_overlay

Add a shape overlay on top of a clip.

**videoId** `string` *required*

Video ID

**clipId** `string` *required*

Clip ID

**startTimeMs** `integer` *required*

Start time in ms on the clip playback timeline

**durationMs** `integer` *required*

Duration in ms

**shapeType** `enum\<string\>`

`square`, `circle`, `triangle`, `diamond`, `star`, `hexagon`, `arrow`, or `path`. Defaults to `square`. `path` needs `path` data

**path** `string`

SVG path data in a 0–100 box. See [Custom paths](#custom-paths)

**fill** `object`

What fills the shape: any clip background object except `ambient`. Defaults to solid Tella purple

**corners** `enum\<string\>`

How a square's corners are rounded: `none`, `regular`, or `squircle`

**border** `object | null`

`{color, width}`: a line just inside the outline, `color` as `#RRGGBB` or `#RRGGBBAA` and `width` in artboard pixels. `null` for none

**shadow** `enum\<string\>`

Drop shadow: `none`, `subtle`, or `deep`

**point** `object`

Top-left corner, `{xPct, yPct}`, as a percentage of the video canvas

**dimensions** `object`

Shape box size in artboard pixels, `{width, height}`

**depth** `enum\<string\>`

`front` (default) or `behind_presenter`

**depthChanges** `array`

Changes of `depth` over the overlay's own time, as on [`add_overlay`](https://www.tella.com/docs/mcp-tools/overlays#add_overlay)

**animation** `object`

Entrance and exit animation. See [Animate overlays](https://www.tella.com/docs/mcp-tools/overlays.md#animate-overlays)

**name** `string`

Label in the editor's timeline

## update\_shape\_overlay

Update a shape overlay. Only the fields you send change. It takes every style, placement, and timing field of `add_shape_overlay` except `name`, plus:

**videoId** `string` *required*

Video ID

**clipId** `string` *required*

Clip ID

**shapeOverlayId** `string` *required*

Shape overlay ID

**transition** `enum\<string\>`

`smooth` fades the shape in and out, `hard_cut` pops it. Setting it without `animation` removes the animation

**animation** `object | null`

Entrance and exit animation. An omitted `intro` or `outro` keeps that side; `null` removes the animation

**zIndex** `integer`

Stacking position, 0 at the back. A value past the top moves the overlay to the front

## remove\_shape\_overlay

Remove a shape overlay from a clip.

**videoId** `string` *required*

Video ID

**clipId** `string` *required*

Clip ID

**shapeOverlayId** `string` *required*

Shape overlay ID

## Batch edits

[`apply_video_edits`](https://www.tella.com/docs/mcp-tools/batch-edits) accepts `add_shape_overlay`, `update_shape_overlay`, and `remove_shape_overlay` operations with the same fields as these tools.


## Related topics

- [Remove a shape overlay](https://www.tella.com/docs/api-reference/clips/remove-a-shape-overlay.md)
- [Update a shape overlay](https://www.tella.com/docs/api-reference/clips/update-a-shape-overlay.md)
- [List shape overlays on a clip](https://www.tella.com/docs/api-reference/clips/list-shape-overlays-on-a-clip.md)
- [Add a shape overlay to a clip](https://www.tella.com/docs/api-reference/clips/add-a-shape-overlay-to-a-clip.md)
- [Overlays overview](https://www.tella.com/docs/help/editing/overlays.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.