Text overlays

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 unless you pass animation, and appear in front; use update_text_overlay to change their transition, stacking order, or placement behind the presenter. Placement behind the presenter works in any layout; fullscreen and framed layouts keep the recorded room, so you do not need a cut-out layout. For a designed look, pass a presetId instead of styling by hand. Text presets are the tiles in the editor’s Text panel — Tella’s built-in styles (default:title, default:caption, default:label, …) and the ones the user saved — and a preset fills in the font, weight, width, color, size, alignment, background, background shape and outline at once (the shadow isn’t part of a preset, matching the editor). Any of those fields sent alongside overrides the preset’s value, the same as picking a tile and then tweaking it. 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 built-in 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.

Animate text overlays

Pass animation to add_text_overlay or update_text_overlay, the matching REST API routes, or the same operations in apply_video_edits. Use intro / outro for the whole text box, with the presets and controls for media overlays. Use textIntro / textOutro to animate individual letters, words, or lines alongside the whole-box animation:

{
  "textIntro": {
    "preset": "slide_up",
    "durationMs": 300,
    "text": {"unit": "words", "order": "forward", "delayMs": 100}
  },
  "outro": {"preset": "fade"}
}

text.unit is required on a new text side: letters, words, or lines.
text.order is forward (default), backward, center, edges, or random. Random order uses the same shuffle every time.
text.delayMs sets the gap between units, 0–2000 ms (default 100). durationMs sets how long each unit animates.
text.smoothing eases the delays across units. It defaults to linear and accepts the other easing curve names except bounce, custom, and spring.
On text sides, moveX / moveY are fractions of the line height, not the whole text box. Whole-box sides do not accept text settings.

Whole-box and per-unit intros start together; their outros end together. Omitted sides stay unchanged on updates, and a side set to null is removed. Send animation: null to remove all animation and restore transition; setting transition without animation also removes the animation.

Use a custom font

You can use a custom font from your private or workspace library instead of a catalog fontFamily.

Call list_library with type: "font" and scope: "private" or "workspace" to find an uploaded font. To upload a new one, call create_source with kind: "font", PUT a .ttf or .otf file of at most 20 MB to its uploadUrl, then save its sourceId with add_library_item.
Pass the font library item’s id as fontId to add_text_overlay or update_text_overlay. Do not send fontFamily in the same request; combining them is an error.

If you omit fontWeight when selecting a library font, Tella uses the family’s default face weight when available, matching the editor’s font picker. You can also use fontId in the matching apply_video_edits operations. A font outside your private or workspace library is rejected.

list_text_overlays

List the text overlays on a clip. Overlays using a library font include its fontId alongside fontFamily. Image and video overlays are listed separately by list_overlays. Each result includes its zIndex in the shared image, video, text, and Lottie overlay stack, from 0 (back) upward. Lottie overlays share the stack but aren’t listed, so the reported positions can skip a number.

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

string

A preset from list_text_presets — default:<id> for a built-in style or a saved preset’s ID. Supplies every style field below; fields sent alongside override it

enum<string>

One of the catalog fonts listed above. Defaults to Inter; use fontId instead for a custom font

string

The id of a font item in your private or workspace library. Do not combine with fontFamily

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, or the library font’s default face weight when available

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

Show properties

enum<string>

required

Background variant. Text overlays take a solid background. One of solid.

string

required

Hex color string, #RRGGBB or #RRGGBBAA. Required when type = ‘solid’.

enum<string>

Background shape — none, regular, or squircle. Defaults to none

string | null

Outline (stroke) color around the letters, #RRGGBB or #RRGGBBAA. Defaults to no outline, or the preset’s

enum<string>

Drop shadow — none, subtle, or deep, the editor’s Shadow menu. It falls from the background box when there is one, else from the letters. Defaults to none

object

Top-left corner — {xPct, yPct} (0-100), as a percentage of the video canvas

Show properties

number

required

0-100

number

required

0-100

object

Text box size in artboard pixels — {width, height}, both greater than 0

Show properties

number

required

Width in artboard pixels, greater than 0

number

required

Height in artboard pixels, greater than 0

object

Whole-box or per-unit entrance and exit animation. See Animate text overlays.

update_text_overlay

Update an existing text overlay — its copy, font, text color, background, timing, position, size, transition, or depth. Only provided fields change.

string

required

Video ID

string

required

Clip ID

string

required

Text overlay ID

string

New text

string

Restyle the overlay with a preset from list_text_presets; its text, timing and placement stay. Style fields sent alongside override the preset’s values

enum<string>

New font family, one of the catalog fonts listed above. Switches away from any library font; do not combine with fontId

string

The id of a font item in your private or workspace library. Selects that font and its default face weight when available, unless you also pass fontWeight. Do not combine with fontFamily

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

Show properties

enum<string>

required

Background variant. Text overlays take a solid background. One of solid.

string

required

Hex color string, #RRGGBB or #RRGGBBAA. Required when type = ‘solid’.

enum<string>

New background shape — none, regular, or squircle

string | null

New outline color, #RRGGBB or #RRGGBBAA; null removes the outline

enum<string>

New drop shadow — none, subtle, or deep

integer

New start time in ms

integer

New duration in ms

object

New top-left — {xPct, yPct} (0-100)

Show properties

number

required

0-100

number

required

0-100

object

New size in artboard pixels — {width, height}, both greater than 0

Show properties

number

required

Width in artboard pixels, greater than 0

number

required

Height in artboard pixels, greater than 0

object | null

Update whole-box or per-unit animation; null restores transition. See Animate text overlays.

enum<string>

Intro and outro animation — smooth fades the text in and out, while hard_cut makes it appear and disappear instantly. Setting this without animation removes any animation.

enum<string>

front paints the text over everything. behind_presenter places it behind the presenter (the person in the clip’s camera recording, or in its uploaded footage when there is no camera) but over everything else. In fullscreen and framed layouts the recorded room stays around the person, so the text sits between the room and them; a cut-out layout replaces the room with the clip background. Without a presenter, the text stays in front.

integer

Stacking position, 0 at the back. Must be non-negative; a value past the top moves the text to the front. Other overlays keep their relative order.

list_text_overlays, add_text_overlay, and update_text_overlay return the current animation (or null), transition, depth, and zIndex. depth takes precedence over stacking order: behind_presenter stays behind the presenter at any zIndex. The video timeline also reports zIndex; apply_video_edits does not support reordering overlays.

remove_text_overlay

Remove a text overlay from a clip.

string

required

Video ID

string

required

Clip ID

string

required

Text overlay ID

Text presets

A text preset is everything about a text overlay except its text, timing and placement. Its style carries fontFamily, fontWeight, fontWidth, color, textAlign, background, backgroundShape, outline and a fontSizeScale — the size relative to the editor’s default (7.5% of the canvas’s shorter side), so the same preset reads the same on every canvas. Adding an overlay with a preset resolves that scale to artboard pixels for the video it lands on.

list_text_presets

List Tella’s built-in text styles and the presets saved by the authenticated user. Each result has a presetId, name, scope (default or personal) and its style. Pass a returned presetId to add_text_overlay, update_text_overlay, or the same operations in apply_video_edits.

save_text_preset

Save a personal text preset, like the editor’s “Save style” on a text overlay. The style starts from an existing text overlay when videoId and textOverlayId are given — which keeps a custom font and reads the size relative to that video’s canvas — else from the editor’s default text look. Every style field passed alongside overrides it. The preset then shows up in list_text_presets and in the editor’s Text panel for the same user.

string

required

Preset name, as shown in the editor

string

Video holding the text overlay to copy the style from. Goes together with textOverlayId

string

Text overlay to copy the style from. Goes together with videoId

enum<string>

One of the catalog fonts listed above

number

Variable-font weight axis — 100 (thin) to 900 (black)

number

Variable-font width axis, as a percentage — 100 is normal

string

Hex color, #RRGGBB or #RRGGBBAA

number

Font size relative to the editor’s default: 1 is the default, 0.6 a caption, 1.4 a headline. Defaults to 1, or to the copied overlay’s size

enum<string>

left, center, or right

object

Background behind the text — { type: "solid", color }

enum<string>

none, regular, or squircle

string | null

Outline color, #RRGGBB or #RRGGBBAA, or null for none

delete_text_preset

Delete one of the authenticated user’s saved text presets. Built-in default: presets can’t be deleted, and text overlays already styled with the preset keep their look.

string

required

A personal preset ID from list_text_presets

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Text overlays

Animate text overlays

Use a custom font

list_text_overlays

add_text_overlay

update_text_overlay

remove_text_overlay

Text presets

list_text_presets

save_text_preset

delete_text_preset

​Animate text overlays

​Use a custom font

​list_text_overlays

​add_text_overlay

​update_text_overlay

​remove_text_overlay

​Text presets

​list_text_presets

​save_text_preset

​delete_text_preset

Animate text overlays

Use a custom font

list_text_overlays

add_text_overlay

update_text_overlay

remove_text_overlay

Text presets

list_text_presets

save_text_preset

delete_text_preset