Skip to main content
Put text on top of a clip for a time range — a title, callout, lower third or label. Nothing needs uploading: pass the copy directly. Position uses a percentage point and a pixel dimensions box, exactly like image and video overlays, and fontSize is in the same artboard pixels as dimensions so text keeps its size relative to the frame. Every styling field has a default taken from the editor, so text, startTimeMs and durationMs are usually all you need: Inter at 500 weight, white, center-aligned, no background, sized to 7.5% of the video’s shorter side, in a centered box 60% of the artboard wide and 25% tall. New text overlays start with a hard cut; use update_text_overlay to make them fade in and out. A weight or width outside the chosen font’s own variable axis range is clamped when the video renders, the same way the editor clamps it. fontFamily must be one of Tella’s catalog fonts — the same list the editor’s font picker offers, and the only families the renderer bundles: Archivo, Barlow, Caveat, DM Sans, Figtree, Inter, Lora, Merriweather, Montserrat, Nunito Sans, Open Sans, Oswald, Playfair Display, Poppins, Raleway, Roboto, Roboto Flex, Roboto Mono, Source Sans 3, Space Grotesk. Anything else is rejected with a 400 rather than silently rendering as Inter. Reading is looser than writing: an overlay made before that catalog can report a different family it still renders with, so list_text_overlays may return a family you couldn’t set. Updating such an overlay’s text or timing works normally — the check only applies when you send fontFamily yourself.
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.

​
list_text_overlays

List the text overlays on a clip. Image and video overlays are listed separately by list_overlays.
​
string
required
Video ID
​
string
required
Clip ID

​
add_text_overlay

Add a text overlay on top of a clip.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
The text to display
​
integer
required
Start time in ms
​
integer
required
Duration in ms
​
enum<string>
One of the catalog fonts listed above. Defaults to Inter
​
number
Font size in artboard pixels. Defaults to 7.5% of the video’s shorter side
​
string
Hex color, #RRGGBB or #RRGGBBAA. Defaults to white
​
number
Variable-font weight axis — 100 (thin) to 900 (black). Defaults to 500
​
number
Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded. Defaults to 100
​
enum<string>
Horizontal alignment inside the text box — left, center, or right. Defaults to center
​
object
Background behind the text, in the same object shape as a clip background — { type: "solid", color }, with color as #RRGGBB or #RRGGBBAA. Defaults to transparent
​
enum<string>
Background shape — none, regular, or squircle. Defaults to none
​
object
Top-left corner — {xPct, yPct} (0-100), as a percentage of the video canvas
​
object
Text box size in artboard pixels — {width, height}, both greater than 0

​
update_text_overlay

Update an existing text overlay — its copy, font, text color, background, timing, position, size, or transition. Only provided fields change.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
Text overlay ID
​
string
New text
​
enum<string>
New font family, one of the catalog fonts listed above
​
number
New font size in artboard pixels
​
string
New hex color, #RRGGBB or #RRGGBBAA
​
number
New weight — 100 (thin) to 900 (black)
​
number
New width axis, as a percentage
​
enum<string>
New horizontal alignment inside the text box — left, center, or right
​
object
New background behind the text — { type: "solid", color }, with color as #RRGGBB or #RRGGBBAA
​
enum<string>
New background shape — none, regular, or squircle
​
integer
New start time in ms
​
integer
New duration in ms
​
object
New top-left — {xPct, yPct} (0-100)
​
object
New size in artboard pixels — {width, height}, both greater than 0
​
enum<string>
Intro and outro animation — smooth fades the text in and out, while hard_cut makes it appear and disappear instantly.
list_text_overlays and update_text_overlay return the current transition for every text overlay.

​
remove_text_overlay

Remove a text overlay from a clip.
​
string
required
Video ID
​
string
required
Clip ID
​
string
required
Text overlay ID