Skip to main content
POST
Add a text 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 a text overlay to a clip. Nothing needs uploading — pass the copy directly. When point/dimensions are omitted, a centered box 60% of the artboard wide and 25% tall is used.

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

text
string
required
Minimum string length: 1
Example:

"Welcome back"

background
object

Background behind the text. Defaults to transparent.

backgroundShape
enum<string>

Defaults to none.

Available options:
none,
regular,
squircle
Example:

"squircle"

color
string

Defaults to white.

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

"#FFFFFFFF"

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.

fontFamily
enum<string>

One of Tella's catalog font families. Defaults to Inter. Anything outside the catalog is rejected rather than silently falling back.

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. Defaults to 7.5% of the video's shorter side, which is the editor's default and readable at any canvas size.

Required range: x > 0
Example:

81

fontWeight
number

Variable-font weight axis — 100 (thin) to 900 (black), 500 by default. Values outside the chosen font's own axis range are clamped when rendered.

Required range: 1 <= x <= 1000
Example:

500

fontWidth
number

Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded, 100 by default. Values outside the chosen font's own axis range are clamped when rendered.

Required range: x > 0
Example:

100

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.

textAlign
enum<string>

Defaults to center.

Available options:
left,
center,
right
Example:

"center"

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.