Skip to main content
PATCH
Update a text 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

textOverlayId
string
required

Text overlay ID

Body

application/json

Update an existing text overlay

background
object

Background behind a text overlay, in the same object shape as a clip background.

backgroundShape
enum<string>

Shape of the solid background behind the text.

Available options:
none,
regular,
squircle
Example:

"squircle"

color
string

Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
Example:

"#FFFFFFFF"

depth
enum<string>

Where the overlay sits relative to the presenter on a clip with a camera layout: front paints over everything, behind_presenter tucks it behind the cut-out presenter but above the clip background and screen. New overlays start on front. Without a camera in the layout the overlay paints in front either way.

Available options:
front,
behind_presenter
Example:

"behind_presenter"

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
fontFamily
enum<string>

One of Tella's catalog font families — the same list the editor's font picker offers.

Available options:
Inter,
Roboto Mono,
Archivo,
Barlow,
Caveat,
DM Sans,
Figtree,
Lora,
Merriweather,
Montserrat,
Nunito Sans,
Open Sans,
Oswald,
Playfair Display,
Poppins,
Raleway,
Roboto,
Roboto Flex,
Source Sans 3,
Space Grotesk
Example:

"Inter"

fontSize
number

Font size in artboard pixels.

Required range: x > 0
fontWeight
number
Required range: 1 <= x <= 1000
fontWidth
number
Required range: x > 0
outline
string | null

Set an outline color, or null to remove the outline.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
Example:

"#000000FF"

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.

presetId
string

Restyle the overlay with a preset from GET /v1/text-presets; its text, timing and placement stay. Style fields sent alongside override the preset's values.

Minimum string length: 1
Example:

"default:label"

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"

startTimeMs
integer

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

Required range: 0 <= x <= 9007199254740991
text
string
Minimum string length: 1
textAlign
enum<string>

Horizontal alignment of the text inside its overlay box.

Available options:
left,
center,
right
Example:

"center"

transition
enum<string>

Intro/outro animation: smooth fades the text in at its start and out at its end, hard_cut pops it in and out.

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 text overlay on a clip

textOverlay
object
required

A text overlay on a clip. Unlike image and video overlays it references no source — the copy and its font live on the overlay itself.

Last modified on October 6, 2026