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 and appear in front; use update_text_overlay to change their transition or place them behind a cut-out presenter. 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 and background shape at once. 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 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.

​

list_text_overlays

List the text overlays on a clip. Image and video overlays are listed separately by list_overlays.

​

add_text_overlay

Add a text overlay on top of a clip.

​

update_text_overlay

Update an existing text overlay — its copy, font, text color, background, timing, position, size, transition, or depth. Only provided fields change. list_text_overlays and update_text_overlay return the current transition and depth for every text overlay.

​

remove_text_overlay

Remove a text overlay from a clip.

​

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 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.

​

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.