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.
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 options of image and video overlays. Their timing follows the footage like text overlays: cutting out footage under a shape shortens it.
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
Sendpath 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 itsborder, 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.
list_shape_overlays
List the shape overlays on a clip. Each result includes itsid, shapeType, path (or null), fill, corners, border, shadow, timing, point, dimensions, transition, depth, and zIndex.
string
required
Video ID
string
required
Clip ID
add_shape_overlay
Add a shape overlay on top of a clip.string
required
Video ID
string
required
Clip ID
integer
required
Start time in ms on the clip playback timeline
integer
required
Duration in ms
enum<string>
square, circle, triangle, diamond, star, hexagon, arrow, or path. Defaults to square. path needs path datastring
SVG path data in a 0–100 box. See Custom paths
object
What fills the shape: any clip background object except
ambient. Defaults to solid Tella purpleenum<string>
How a square’s corners are rounded:
none, regular, or squircleobject | null
{color, width}: a line just inside the outline, color as #RRGGBB or #RRGGBBAA and width in artboard pixels. null for noneenum<string>
Drop shadow:
none, subtle, or deepobject
Top-left corner,
{xPct, yPct}, as a percentage of the video canvasobject
Shape box size in artboard pixels,
{width, height}enum<string>
front (default) or behind_presenterarray
Changes of
depth over the overlay’s own time, as on add_overlayobject
Entrance and exit animation. See Animate overlays
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 ofadd_shape_overlay except name, plus:
string
required
Video ID
string
required
Clip ID
string
required
Shape overlay ID
enum<string>
smooth fades the shape in and out, hard_cut pops it. Setting it without animation removes the animationobject | null
Entrance and exit animation. An omitted
intro or outro keeps that side; null removes the animationinteger
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.string
required
Video ID
string
required
Clip ID
string
required
Shape overlay ID
Batch edits
apply_video_edits accepts add_shape_overlay, update_shape_overlay, and remove_shape_overlay operations with the same fields as these tools.