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 unless you pass animation. Use animation on adds or updates to make them fade, slide, scale, rotate, or blur in and out.
  • New overlays start in front. Pass depth to add_overlay or update_overlay to place one behind the person on camera, and zIndex on update_overlay to change their stacking order. That works in any layout: a fullscreen clip keeps its room, with the overlay between the room and the person, so it needs no cut-out 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.

​
Animate overlays

Pass animation to add_overlay or update_overlay to animate the overlay’s entrance and exit. The same input works on the matching REST API routes and the add_media_overlay / update_media_overlay operations in apply_video_edits.
  • intro moves from a hidden state into the overlay’s resting position; outro moves back to a hidden state.
  • preset can be fade, slide_up, slide_down, slide_left, slide_right, mask_up, mask_down, grow, shrink, blur, or blur_slide_up. Directions describe travel: slide_up enters from below and exits upwards.
  • Customize a side with moveX / moveY (fractions of the overlay’s width / height, positive right / down), rotate (clockwise degrees), scale (1 is resting size), opacity (0–1), blur (0–200 pixels), or clip (restrict motion to the overlay’s box).
  • durationMs is 50–5000 ms, defaulting to 500 for a new side. Entrance and exit durations shorten together if they cannot fit the overlay’s time range.
  • easing takes a curve: linear, smooth, natural, slow_down, accelerate, elastic, bounce, overshoot, impulse, swing, custom, or spring. Shaped curves accept intensity from 0–1 (default 0.5). For custom, supply bezier: [x1, y1, x2, y2]; for spring, supply spring: {stiffness, damping, mass}. Spring physics determine the duration.
  • motionBlur defaults to true; set it to false to disable motion blur for this overlay.
On updates, an omitted side stays unchanged; intro: null or outro: null removes that side. A side starts from the supplied preset, or its current settings, and other supplied fields adjust it. An animation replaces transition. Send animation: null on an update to restore the stored transition. Setting transition without animation also removes the animation. Unsupported combinations return an argument error (HTTP 400 on REST); in a batch, validation rejects the whole batch before any edits apply.

​
list_overlays

List the image, video and Tella Motion overlays on a clip. A Tella Motion overlay is listed with type: "motion" and the motionDocumentId it plays. 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
Source ID from create_source. Pass this or motionDocumentId.
​
string
In place of sourceId: a Tella Motion document of this video’s (ffd_…), from create_motion_document, or one of yours that no video plays yet, which this video then takes over. It is linked, not copied, so edits to the document show in the video at once. The document must not play anywhere else yet; one that another overlay, b-roll or clip plays returns 409, so copy it with duplicate_motion_document first.
​
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
​
enum<string>
front (default) or behind_presenter, the same values as update_overlay.
​
array
Changes of depth over the overlay’s own time, each held until the next: {"atMs": 1200, "depth": "front"} moves it in front of the presenter 1.2 s after the overlay starts, so one overlay can pass behind and in front of them (a ring orbiting their head, a title they step in front of). depth is where it starts. On updates, omit it to leave the changes as they are and pass [] to remove them. The same field works on the matching REST routes and apply_video_edits operations.
​
object
Entrance and exit animation. See Animate overlays.

​
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
​
object | null
Update entrance and exit animation; null restores transition. See Animate overlays.
​
enum<string>
Intro and outro animation — smooth fades the overlay in and out, while hard_cut makes it appear and disappear instantly. Setting this without animation removes any animation.
​
enum<string>
front paints the overlay over everything. behind_presenter places it behind the presenter (the person in the clip’s camera recording, or in its uploaded footage when there is no camera) but over everything else. In fullscreen and framed layouts the recorded room stays around the person, so the overlay sits between the room and them; a cut-out layout replaces the room with the clip background. Without a presenter, the overlay stays in front.
​
array
Changes of depth over the overlay’s own time, each held until the next: {"atMs": 1200, "depth": "front"} moves it in front of the presenter 1.2 s after the overlay starts, so one overlay can pass behind and in front of them (a ring orbiting their head, a title they step in front of). depth is where it starts. On updates, omit it to leave the changes as they are and pass [] to remove them. The same field works on the matching REST routes and apply_video_edits operations.
​
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 animation (or null), 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. To reorder several overlays in one call, pass zIndex on update_media_overlay operations in apply_video_edits.

​
remove_overlay

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