Tella

Add a video to a playlist.

add_video_to_playlist

Add one zoom on the footage in the clip's Screen slot at startTimeMs — the screen recording, or b-roll media a layout puts there (the camera is unaffected). 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. Zooms are for screen footage: an uploaded clip can be camera-only (check layoutSceneType with list_layouts), and a punch-in on a person is a fullscreen layout with style stretch. 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

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, image, a .cube LUT, or a font file). 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. To reuse an uploaded source in other videos, save it to the workspace library with `add_library_item` (`scope: 'workspace'`); `list_library` then finds it from any video. For a 3D .cube LUT set `kind: 'lut'` and omit `width`, `height` and `duration`; PUT the .cube file unchanged, then save it with `add_library_item` to get the LUT id that `set_clip_filters` takes. For a custom font set `kind: 'font'` and omit `width`, `height` and `duration`; PUT one TrueType (.ttf) or OpenType (.otf) file unchanged, then save it with `add_library_item` to get the font id that text overlays take as `fontId`.

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 one of the authenticated user's saved text presets. Built-in `default:` presets can't be deleted. Text overlays already styled with the preset keep their look.

delete_text_preset

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

Deprecated: to lay a clip out automatically, use the `tella-auto-layouts` skill from tellahq/skills (`npx skills add tellahq/skills`), which plans layouts from the transcript and frames and applies them with `apply_video_edits`, keeping the clip's camera style and pop-out. This tool keeps working for now. 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

Measure how loud a clip's voice track is over a stretch of its playback timeline (cuts applied, the same times as get_transcript and get_silences). Returns the peak level in dBFS for each step (0 is full scale; speech is usually above about -30, room tone well below -40; null where there is no audio). Levels come from stored waveform buckets about 5 ms long (`resolutionMs`), so a step right next to a cut can include a little of the cut audio. Use it to check what is left at a cut, find a breath, click or filler the transcript misses, or see where speech really starts and ends. It reads the stored waveform, so it is instant; there's no need to download the audio and measure it yourself.

get_audio_levels

Get a video's ready captions as SRT or WebVTT text, for exporting or reviewing caption wording. Cue times are whole-video playback time (every clip in order, cuts applied), not the clip playback time the editing tools take, so never place a layout, overlay, zoom or sound effect by them: read the words' times with get_transcript on that clip instead.

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 the colour filters (the editor's Style → Filters) on a clip's camera and screen recordings: the matching preset (or 'custom'), exposure, contrast, saturation, temperature, tint and any LUT. `camera` or `screen` is null when the clip has no such recording. Filters show in the editor and in exports rendered by the new render engine.

get_clip_filters

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. Waits up to a minute for the render: `status: "ready"` means the URL downloads immediately; `status: "rendering"` means call again with the same arguments to keep waiting (no second render starts). 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. Pass startTimeMs/endTimeMs to read just a window of a long recording; a window returns the same events the whole-clip response has in that range.

get_mouse_events

Get detailed information about a playlist.

get_playlist

Get a source's processing status by the `sourceId` from `create_source`, however it was placed (clip, b-roll, overlay, background, background music or sound effect). `pending`: the upload hasn't arrived yet; a video or audio source starts converting as soon as it does, an image is prepared within a few seconds, and a LUT or font is ready right away. `processing`: still uploading or converting; frames and previews of videos using it answer not-ready until then, so poll this every few seconds. `ready`: usable everywhere. `failed`: conversion failed or the recording was cancelled; upload the file again as a new source.

get_source

Get a thumbnail of a source. Pass videoId and clipId for a source on a clip, or sourceId alone for one not on any clip yet (such as a chat attachment). 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