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.
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.
​
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.
list_overlays and update_overlay return the current transition for every overlay.

​
remove_overlay

Remove an overlay from a clip.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
Overlay ID