Skip to main content
POST
Add an overlay to a clip

Authorizations

Authorization
string
header
required

API key obtained from your Tella account settings

Path Parameters

id
string
required

Video identifier

Example:

"vid_abc123def456"

clipId
string
required

Clip identifier

Example:

"cl_xyz789ghi012"

Body

application/json

Add an image or video overlay to a clip. Upload the bytes via POST /v1/sources (kind: image or kind: video) and pass the sourceId; the overlay type follows the source's kind. Or pass motionDocumentId to show a Tella Motion document of the video's. When point/dimensions are omitted, a centered box is computed from the source.

durationMs
integer
required
Required range: 0 < x <= 9007199254740991
Example:

5000

startTimeMs
integer
required

Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.

Required range: 0 <= x <= 9007199254740991
Example:

1000

animation
object

How the overlay enters and leaves; when set it replaces transition. Each side describes the hidden state the overlay moves from on the way in and back to on the way out. An omitted side stays as it is. {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}} is a complete animation; on text, {textIntro: {preset: 'slide_up', text: {unit: 'words'}}} brings the words in one by one.

Example:
depth
enum<string>

Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. front paints over everything. behind_presenter paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on front. Without a presenter the overlay paints in front either way.

Available options:
front,
behind_presenter
Example:

"behind_presenter"

depthChanges
object[]

Changes of depth over the overlay's own time, each held until the next: atMs after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind 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; [] removes them. Absent in responses while the overlay holds one depth.

dimensions
object

Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning.

motionDocumentId
string

In place of sourceId: a Tella Motion document of this video's (ffd_…, from POST /v1/motion/documents), shown as the overlay. It is linked, not copied: it plays live, so edits to the document show in the video at once.

Example:

"ffd_abc123"

name
string
Example:

"Logo"

point
object

Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes.

sourceId
string

Source ID from POST /v1/sources (kind: image or kind: video). The overlay type follows the source's kind. Pass this or motionDocumentId.

Example:

"su_abc123"

transition
enum<string>

Intro/outro animation: smooth fades the overlay in at its start and out at its end, hard_cut pops it in and out. An animation replaces it while set.

Available options:
smooth,
hard_cut
Example:

"smooth"

Response

OK

An overlay on a clip

overlay
object
required

An image, video or Tella Motion overlay on a clip.