Tella

Add one zoom on the clip's screen layer (does not affect the camera). For two or more additions, use apply_video_edits instead. Use 'manualZoom' with a focusPoint to zoom into a fixed location, or 'trackingZoom' to follow the cursor automatically. Times are in ms on the clip's playback timeline (cuts applied) — the same timeline as get_transcript and thumbnails. Internally the zoom stays anchored to the footage, so it doesn't drift when cuts change later.

add_zoom

Apply one of the caller's saved Favorite layouts to a clip. Omit the range to set the clip-spanning base layout, or provide startTimeMs and durationMs to apply it to a range. Custom favorites must match the clip's scene type and canvas ratio.

apply_saved_layout

Apply a preset from list_subtitle_presets to a video. Built-in presets set style, font, weight, and size while preserving position, grouping, and lines per block. Saved presets also restore position, grouping, and lines per block. Replaces the current subtitle appearance without changing transcript text or whether subtitles are enabled; use update_video to enable subtitles. Changes sync to open editors. Reapplying the same preset is safe.

apply_subtitle_preset

Add, update, and remove many timeline elements on one video in a single call and one editor revision. Use this whenever you need TWO OR MORE supported edits, even when they are different kinds, mix adds with updates and removes, or belong to different clips. It is much faster and safer than repeatedly calling the single-edit tools (add_zoom, update_text_overlay, remove_sound_effect, …). Operation `type` values: add_sound_effect, add_text_overlay, add_zoom, add_blur, add_highlight, add_media_overlay, add_layout, update_zoom, remove_zoom, update_blur, remove_blur, update_highlight, remove_highlight, update_media_overlay, remove_media_overlay, update_text_overlay, remove_text_overlay, update_sound_effect, remove_sound_effect, update_layout, remove_layout — each takes the same fields as the tool of that name, minus videoId. Layout adds and updates support b-roll `media`, including media-only adds that choose the default full-frame layout. Cuts, transcript edits, clip settings, and auto layouts are not batchable. Operations run in array order and each operationId is returned with the created or affected resource ID. An update or remove may target a resource added earlier in the same batch by using that add's operationId in place of the resource ID. The complete batch is validated before editor content is changed. Supports up to 200 operations.

apply_video_edits

Detect and apply a crop to the clip's screen recording at a selected frame. The optional inpoint is in ms on the clip playback timeline (cuts applied) and defaults to 0. Existing masks and custom-layout geometry are adjusted with the crop.

auto_crop

Capture a public web page or a single social post on X, Instagram, LinkedIn or TikTok using Tella's URL-to-screenshot feature. Web pages are captured above the fold at 1920×1080; social posts are cropped to their embed card. Set scroll to true to record a scrolling web page as a video (ignored for social posts). Private pages and social profiles/feeds are not supported. Wait for this call to finish (up to two minutes): it returns a ready private library item, not an asynchronous generation. Stills have type 'image'; scrolling pages have type 'video'. Pass item.sourceId to add_overlay, add_layout (media), or apply_video_edits. The result also appears in list_library with scope 'private'. This saves reusable media; it does not edit a video. Use an idempotency key when retrying to avoid duplicate captures.

capture_screenshot

Create a new playlist.

create_playlist

Create a sidebar group to organize playlists into. Use move_playlist_to_group to put playlists in it.

create_playlist_group

Create a new source upload (video, audio, or image). Use this to add a new clip (via `upload_clip`), b-roll media on a clip (via `add_layout`/`update_layout` `media.sourceId`), an overlay (`add_overlay`), a clip background (`update_clip`), background music (`set_background_music`), or a sound effect (`add_sound_effect`). Returns a `sourceId` and a pre-signed `uploadUrl`; PUT the file bytes to `uploadUrl`, then reference `sourceId`. Upload the file as-is: any common container works (MP4, MOV, WebM, MP3, WAV, M4A, …) — the `.mp4` in the upload URL is just the storage key, not a container requirement, so never remux or re-encode first. For audio files set `kind: 'audio'` with the audio's duration and omit `width`/`height`. For images set `kind: 'image'` and omit `duration`; Tella hosts the bytes for rendering — you never deal with raw image URLs.

create_source

Create a tag for categorizing videos. When no color is given, one is derived from the name.

create_tag

Create a new video from an uploaded source. Call `create_source` first (`kind: 'video'`), PUT the bytes to the returned `uploadUrl`, then pass the `sourceId` here — it becomes the new video's first clip.

create_video

Cut one or more time ranges from a clip in a single call. Overlapping or adjacent ranges are merged into the existing cuts. To clear all cuts, call update_clip with cuts: [].

cut_clip

Cut ranges from a clip by referencing word indices in the transcript. Use this when you've already decided which words to remove — the server resolves each word's exact start/end ms so you don't have to. Word indices come from get_transcript.

cut_clip_by_transcript

Remove a clip from its video. The underlying recording is preserved.

delete_clip

Delete a playlist.

delete_playlist

Delete a playlist group. Playlists in the group are not deleted, they just become ungrouped.

delete_playlist_group

Permanently delete a tag and remove it from all videos.

delete_tag

Delete a video (moves to trash).

delete_video

Duplicate a clip in its video. Inserts the copy after the original by default.

duplicate_clip

Create a copy of a video with optional new name. Supports trimming to extract a time range or specific chapter.

duplicate_video

Start a video export. Returns export status with workflow ID and download URL when complete.

export_video

Let AI watch the clip and lay it out — the same as the editor's "Auto layouts". Replaces the clip's existing layouts: the AI picks an editing style (or follows `style`), sets the clip's base layout, and adds time-ranged layout changes. Generation watches the actual video, so this can take on the order of a minute for longer clips.

generate_auto_layouts

Automatically generate tracking zooms from the mouse clicks in the clip's screen recording — the same as the editor's "Generate zooms". Every click opens a zoom window; nearby windows are merged. Requires the clip to contain a screen recording; returns an empty list when it has no usable mouse clicks. Returned zoom times are in ms on the clip's playback timeline (cuts applied). Warning: by default this REMOVES the clip's existing tracking zooms first (pass replaceExisting: false to keep them); manual zooms are never touched.

generate_auto_zooms

Generate an image from a text prompt with Tella's AI image generator (2048×1152, landscape). Use it for overlays and b-roll stills when there is no file to upload. Generation runs in the background and usually takes 30-90 seconds: the result is a `generation` whose `id` is a private library item that is still being filled in. Poll `get_generation_status` with that `id` every few seconds until `generation.status` is `completed`, then place `generation.item.sourceId` with `add_overlay` (image overlay), `add_layout` (`media: {type: 'image', sourceId}` for a b-roll still), or the same operations inside `apply_video_edits`. The finished item also appears in `list_library` (`scope: 'private'`). Counts against the caller's weekly AI generation quota, which depends on the plan; the response reports `remaining`.

generate_image

Generate a short sound effect from a text prompt with Tella's AI sound generator, for when Tella's curated catalog (`list_library` with `scope: 'default'`) has nothing suitable. Generation runs in the background and usually takes 10-30 seconds: the result is a `generation` whose `id` is a private library item that is still being filled in. Poll `get_generation_status` with that `id` every few seconds until `generation.status` is `completed`, then place `generation.item.sourceId` with `add_sound_effect` (as `sourceId`, not `presetId`) or inside `apply_video_edits`; `generation.item.durationMs` is the effect's length. The finished item also appears in `list_library` (`scope: 'private'`, `type: 'sound-effect'`). Counts against the caller's weekly AI generation quota, which depends on the plan; the response reports `remaining`.

generate_sound_effect

Generate a short b-roll video clip from a text prompt with Tella's AI video generator. Generation runs in the background and can take several minutes: the result is a `generation` whose `id` is a private library item that is still being filled in. Poll `get_generation_status` with that `id` every 5-10 seconds until `generation.status` is `completed`, then place `generation.item.sourceId` as b-roll with `add_layout` (`media: {type: 'video', sourceId}` over a time range; omit `layout` for a full-frame b-roll layout, or set `media.slot: 'camera'` for a bubble), as a video overlay with `add_overlay`, or inside `apply_video_edits`; `generation.item.durationMs` is the clip's length. The finished item also appears in `list_library` (`scope: 'private'`, `type: 'video'`). Counts against the caller's weekly AI generation quota, which depends on the plan; the response reports `remaining`.

generate_video

Get a video's ready captions as SRT or WebVTT text.

get_captions_file

Get every chapter on a video. Timestamps are seconds on the final video timeline. Chapters have no stable IDs; use set_chapters to replace the complete list.

get_chapters

Get a single clip on a video.

get_clip

Get a rendered frame from a clip's playback timeline (cuts applied), including the clip's layouts, b-roll media, zooms, and masks. For jpg/png/webp, returns inline image content plus a signed URL; for gif, returns the signed URL only. Use `get_clip_preview` for an MP4 preview. Available outside your workspace when the video has an ungated public link or appears in a public or embed-only playlist.

get_clip_frame

Get an MP4 preview of a clip's rendered playback timeline (cuts applied), including the clip's layouts, b-roll media, zooms, and masks. Returns a signed URL. Available outside your workspace when the video has an ungated public link or appears in a public or embed-only playlist.

get_clip_preview

Get silent ranges in a clip's audio, in ms on the clip's playback timeline (cuts applied) — pass them directly to cut_clip in the same call's coordinates. Silences already removed by cuts are not reported.

get_silences

Poll this tool after `export_video` until `export.status` is `completed` or `failed`. `export.downloadUrl` appears when the export is ready.

get_export_status

Poll this after `generate_image`, `generate_sound_effect` or `generate_video` until `generation.status` is `completed` or `failed`. While it is `pending` or `running`, wait a few seconds and call again (images take 30-90 seconds, sound effects 10-30 seconds, video several minutes). On `completed`, `generation.item` is the finished library item: pass its `sourceId` to `add_overlay`, `add_sound_effect`, `add_layout` (`media`) or `apply_video_edits`. On `failed`, `generation.error` says why; a failed generation cannot be resumed — start a new one.

get_generation_status

Get the cursor path and clicks recorded with the clip's screen recording, mapped onto the clip's playback timeline (cuts applied) — the same timeline as get_transcript and zooms. Positions are percentages of the screen dimensions (0-100), the same coordinate space as zoom focusPoints. Move events are sampled to one per intervalMs (clicks are always kept) and events in cut-out footage are dropped. Filter with types — e.g. ["clicks"] returns only click positions. A click is the moment a mouse button went down: recordings sample the button state continuously, so a drag yields one click at the press followed by move events, and placing a sound effect on a click lands it on the press rather than somewhere mid-drag. Useful for finding where the user was working before placing zooms. Returns an empty list when the recording has no mouse data.

get_mouse_events

Get detailed information about a playlist.

get_playlist

Get a thumbnail of a source. For jpg/png/webp, returns inline image content plus a signed URL; for gif and mp4, returns the signed URL only. Omit width/height to use the source's native size.

get_source_thumbnail

Get the audio waveform JSON for a source. Returns the BBC audiowaveform format: sample rate, samples per pixel, bit depth, and the raw audio level data array. Useful for rendering custom waveform visualizations.

get_source_waveform

Get a 4x4 storyboard image with 16 tiles sampled evenly across the requested window (durationMs/16 apart; every 5 seconds for the default 80s window) from a story, streaming upload, or clip/scene. Returns inline WebP image content plus JSON with the signed URL, columns, rows, and intervalMs (tile i, row-major, is at startTimeMs + i * intervalMs). Pass videoId alone for a story, videoId with clipId for a rendered clip/scene, or sourceId alone for a streaming upload. Only the time window is configurable.

get_storyboard

Get a compact ordered outline of a video's timeline. Call this first when working on a video: the default response contains video identity/version/dimensions/duration and every clip's timeline position, playback duration, and content counts. Fetch only the details needed with include, optionally scoped with clipIds; the complete outline is still returned for context. Use include=['all'] for the complete edit state. Effect and word times are ms on each clip's playback timeline (cuts applied). Raw cuts retain get_clip's source-recording times. The words detail includes hidden words and stable indices for transcript edits; transcript is visible plain text only.

get_timeline