Skip to main content
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.
  • New overlays start in front. Use update_overlay with zIndex to change their stacking order, or depth to place one behind the cut-out presenter on a clip with a camera layout.
For text, use text overlays.
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.

​
list_overlays

List the image and video overlays on a clip. Each result includes its zIndex in the shared image, video, text, and Lottie overlay stack, from 0 (back) upward. Lottie overlays share the stack but aren’t listed, so the reported positions can skip a number.
​
string
required
Video ID
​
string
required
Clip ID

​
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.
​
string
required
Video ID
​
string
required
Clip ID
​
integer
required
Start time in ms
​
integer
required
Duration in ms
​
string
required
Source ID from create_source
​
string
Overlay name
​
object
Top-left corner — {xPct, yPct} (0-100), as a percentage of the video canvas
​
object
Overlay size in artboard pixels — {width, height}, both greater than 0

​
update_overlay

Update an existing overlay. Only provided fields change.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
Overlay ID
​
integer
New start time in ms
​
integer
New duration in ms
​
string
Overlay name
​
object
New top-left — {xPct, yPct} (0-100)
​
object
New size in artboard pixels — {width, height}, both greater than 0
​
enum<string>
Intro and outro animation — smooth fades the overlay in and out, while hard_cut makes it appear and disappear instantly.
​
enum<string>
front paints the overlay over everything. behind_presenter places it behind the cut-out presenter but above the clip background and screen. Without a camera in the layout, the overlay stays in front.
​
integer
Stacking position, 0 at the back. Must be non-negative; a value past the top moves the overlay to the front. Other overlays keep their relative order.
list_overlays, add_overlay, and update_overlay return the current transition, depth, and zIndex. depth takes precedence over stacking order: behind_presenter stays behind the presenter at any zIndex. The video timeline also reports zIndex; apply_video_edits does not support reordering overlays.

​
remove_overlay

Remove an overlay from a clip.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
Overlay ID
Last modified on September 29, 2026