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, cornerRadius (or null), border, shadow, timing, point, dimensions, transition, depth, and zIndex.
add_shape_overlay
Add a shape overlay on top of a clip.square, circle, triangle, diamond, star, hexagon, arrow, or path. Defaults to square. path needs path dataSVG path data in a 0–100 box. See Custom paths
What fills the shape: any clip background object except
ambient. Defaults to solid Tella purpleThe corners’ radius in story pixels, 0 to 512, replacing their preset’s (
regular is 12% of the shorter side, squircle 24%). Needs corners regular or squircle; setting corners without it, or null on update, goes back to the preset’s{color, width}: a line just inside the outline, color as #RRGGBB or #RRGGBBAA and width in artboard pixels. null for noneChanges of
depth over the overlay’s own time, as on add_overlayEntrance and exit animation. See Animate overlays
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:
smooth fades the shape in and out, hard_cut pops it. Setting it without animation removes the animationEntrance and exit animation. An omitted
intro or outro keeps that side; null removes the animationremove_shape_overlay
Remove a shape overlay from a clip.Batch edits
apply_video_edits accepts add_shape_overlay, update_shape_overlay, and remove_shape_overlay operations with the same fields as these tools.