Skip to main content
PATCH
Update a shape overlay

Authorizations

Authorization
string
header
required

API key obtained from your Tella account settings

Path Parameters

id
string
required

Video ID

clipId
string
required

Clip ID

shapeOverlayId
string
required

Shape overlay ID

Body

application/json

Update an existing shape overlay. Only provided fields change.

animation
object | null

Animate how the shape enters and leaves. An omitted intro/outro keeps that side. Null removes the animation, so transition plays again.

Example:
border
object | null

A line just inside the outline, or null for none.

corners
enum<string>

How a square's corners are rounded.

Available options:
none,
regular,
squircle
Example:

"squircle"

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.

durationMs
integer
Required range: 0 < x <= 9007199254740991
fill
object

What fills the shape, cut to its outline: any clip background except ambient. A solid #00000000 leaves only the border.

path
string

A custom outline as SVG path data (d) in a 0–100 box; it stretches with the overlay box. Sending it makes the shape a path. Closed subpaths (ending in Z) are filled; an open path shows only its border, drawn centred on the line.

Required string length: 1 - 10000
Example:

"M50 0 L100 100 L0 100 Z"

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.

shadow
enum<string>

Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters.

Available options:
none,
subtle,
deep
Example:

"subtle"

shapeType
enum<string>

The outline, stretched to fill the overlay box: a non-square box makes a rectangle or an oval. path draws the overlay's own path.

Available options:
square,
circle,
triangle,
diamond,
star,
hexagon,
arrow,
path
startTimeMs
integer

Start time. Milliseconds on the clip playback timeline (with cuts applied).

Required range: 0 <= x <= 9007199254740991
transition
enum<string>

Intro/outro animation: smooth fades the shape in and out, hard_cut pops it. An animation replaces it while set; setting transition without animation removes the animation.

Available options:
smooth,
hard_cut
Example:

"smooth"

zIndex
integer

Stacking position among the clip's image, video and text overlays: 0 is the backmost. depth applies first — a behind_presenter overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number. A value past the top moves the overlay to the front; the other overlays keep their relative order.

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

0

Response

OK

A shape overlay on a clip

shapeOverlay
object
required

A shape overlay on a clip: a square, circle, star… filled with any clip background.