Clips

A clip is a section of a video — Tella videos are made up of one or more clips. Each clip has its own cuts, layouts, transcript, and editing tools.

Clip tools take milliseconds on the clip’s playback timeline — the clip as watched, with cuts applied, the same timeline as get_transcript, thumbnails, and previews. A start at or past the end of the clip is rejected with a 400.Three kinds of tool on this page use a different timeline, and say so on their startTimeMs:

get_video_frame and get_video_preview count from the video’s playback start, cumulative across clips.
get_source_thumbnail counts from the start of the raw source file — no clip cuts apply. get_storyboard does the same when given a sourceId.
Stored cut definitions (get_clip’s and update_clip’s cuts) describe removed ranges of the raw recording. Cuts are always undoable by replacing them with [].

upload_clip

Add a new clip to a video from an uploaded source. Call create_source first, PUT the bytes to the returned uploadUrl, then pass the sourceId here.

string

required

Video ID

string

required

Source ID returned by create_source

string

Clip name. Defaults to the next Clip N.

list_clips

List clips in a video, ordered by their position.

string

required

Video ID

get_clip

Get a single clip’s details.

string

required

Video ID

string

required

Clip ID

update_clip

Update a clip’s name, ordering, cuts, background, transition, Studio Sound opt-out, audio volumes, animated cursor, or frame styling (corner rounding and border style).

string

required

Video ID

string

required

Clip ID

string

New clip name

integer

New position within the video

object[]

Replaces the clip’s full cut set. Each cut is {startTimeMs, durationMs} in ms of the raw recording (the playback timeline you’d get after clearing all cuts). Pass [] to clear all cuts. To cut what you currently see, use cut_clip instead.

Show properties

integer

required

Start of the cut, in ms of the raw recording.

integer

required

Length of the cut, in ms.

object

Background {type, color?, sourceId?, imageUrl?, videoUrl?, videoDurationSeconds?, gradientColor1?, gradientColor2?, gradientAngle?}. type is one of solid, image, video, gradient. For your own image or video, pass a sourceId from create_source (kind: "image" or kind: "video"). To use a catalog background, pass the exact background object returned by list_backgrounds; arbitrary image and video URLs are rejected.

Show properties

enum<string>

required

Background variant. One of solid, image, video, gradient.

string

Hex color string. Required when type = ‘solid’.

string

Source ID from create_source (kind: 'image' for type = ‘image’, kind: 'video' for type = ‘video’). Required for image/video backgrounds unless using an exact URL from list_backgrounds.

string

Exact hosted image URL from list_backgrounds. Use only when type = ‘image’; arbitrary remote URLs are rejected.

string

Exact hosted video URL from list_backgrounds. Use only when type = ‘video’; arbitrary remote URLs are rejected.

number

Catalog video duration returned by list_backgrounds. The server always uses its canonical duration.

string

Hex color string. Required when type = ‘gradient’.

string

Hex color string. Required when type = ‘gradient’.

integer

Linear gradient angle in degrees. Required when type = ‘gradient’.

enum<string>

How this clip enters from the previous clip — smooth, hard_cut, or default. Use default to remove the clip override and follow the video’s defaultClipTransition. The first clip has nothing to transition from.

boolean

Per-clip Studio Sound opt-out. false disables enhanced audio for this clip while the video-level switch (update_video’s studioSound) stays on; true re-enables it.

number | null

Microphone volume for this clip only, overriding update_video’s microphoneVolume. 1 is the recorded level, 0 mutes it, 2 doubles it. Pass null to clear the override so the clip follows the video again. If the clip has no microphone audio, null is a no-op and a number returns an error.

number | null

System audio (screen or uploaded footage) volume for this clip only, overriding update_video’s systemAudioVolume. Same range and null-to-clear behaviour. If the clip has no system audio, null is a no-op and a number returns an error.

boolean

Draw an animated cursor from captured mouse data on this clip’s screen recording. Errors when the clip has no screen recording.

enum<string>

Corner rounding of the clip’s frames (screen and camera), the editor Style panel’s Shape: none (square), regular (rounded) or squircle (very rounded). A circle camera stays a circle.

enum<string>

Border and shadow around the clip’s frames, the editor Style panel’s Border style: none, subtle-shadow, deep-shadow, transparent, solid-shadow-left, solid-shadow-right (the solid shadow and its direction) or snake. snake keeps the clip’s current snake settings, or the editor’s default.

Use the volumes to fix a balance in one clip — mic too quiet against loud screen audio, or one clip recorded hotter than the rest. get_clip reports each volume as:

a number — this clip overrides the video setting
null — it follows the video
absent — there is nothing to control: no such track, or a recording without audio, like a screen recording made without sharing system audio

It also reports the clip’s transition, plus animatedCursor when the clip has a screen recording. corners and borderStyle style the clip across all of its layouts, like the editor’s Apply to this clip only: other clips keep the video’s styling. get_clip reports the clip’s current corners and borderStyle. The border style reads custom when the clip’s layers were styled one by one or with a retired preset. You can’t write custom.

{"videoId": "vid_…", "clipId": "cl_…", "corners": "squircle", "borderStyle": "subtle-shadow"}

delete_clip

Remove a clip from its video.

string

required

Video ID

string

required

Clip ID

duplicate_clip

Duplicate a clip. The copy is inserted right after the original by default.

string

required

Video ID

string

required

Clip ID to duplicate

string

Name for the new clip

integer

Position for the new clip

reorder_clip

Move a clip to a new position; other clips shift to stay contiguous.

string

required

Video ID

string

required

Clip ID

integer

required

New 0-based position

cut_clip

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

string

required

Video ID

string

required

Clip ID

object[]

required

Array of {fromMs, toMs} ranges to cut, in ms (what you currently see and hear — the same timeline as get_transcript and get_silences). All ranges are resolved against the playback timeline as it is when the call starts, so send every range in one call instead of issuing many cut_clip calls.

Show properties

integer

required

Start of the range to cut, in ms on the clip’s playback timeline.

integer

required

End of the range to cut, in ms on the clip’s playback timeline.

cut_clip_by_transcript

Cut one or more ranges from a clip by referencing word indices in the transcript. The server resolves each word’s exact start/end ms — no padding is applied. Use get_transcript to look up word indices.

string

required

Video ID

string

required

Clip ID

object[]

required

Array of {fromWordIndex, toWordIndex} ranges. Both indices are inclusive and come from the clip’s transcript (indices are stable — already-cut words are simply absent).

Show properties

integer

required

Index of the first word to cut (inclusive).

integer

required

Index of the last word to cut (inclusive).

get_silences

Detect silent ranges in the clip’s audio, in ms on the clip’s playback timeline (cuts applied) — pass them directly to cut_clip. Silences already removed by cuts are not reported.

string

required

Video ID

string

required

Clip ID

integer

Minimum silence length to report, in ms. Defaults to 200.

remove_fillers

Auto-detect and cut filler words (“um”, “uh”, etc.) from the clip’s transcript.

string

required

Video ID

string

required

Clip ID

remove_silences

Auto-detect and cut silent pauses from the clip’s audio, like the editor’s Remove silences tool.

string

required

Video ID

string

required

Clip ID

enum<string>

How aggressively to remove silences — natural cuts pauses longer than 800ms, fast longer than 500ms, faster longer than 300ms. Defaults to natural.

list_sources

List the underlying recordings (camera, screen, mic) the clip was cut from, each with the volume it plays at in this clip: volume is the clip’s own override (null when it inherits) and effectiveVolume is what actually plays. Read these to inspect a mix; change it with update_clip’s microphoneVolume/systemAudioVolume.

string

required

Video ID

string

required

Clip ID

get_clip_frame

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, or webp, returns inline image content the model can see, plus a signed URL. For gif, returns the signed URL only (vision models don’t read animation, so the bytes aren’t inlined).

string

required

Video ID

string

required

Clip ID

enum<string>

jpg (default), png, webp, or gif

integer

Frame offset in ms on the clip’s playback timeline (default 0)

integer

Duration in ms when format is gif

integer

Output width in pixels (default 320). The frame keeps the video’s aspect ratio.

integer

Output height in pixels. Derived from the video’s aspect ratio when omitted.

boolean

Suggest a download disposition on the signed URL

For still images, get_clip_frame, get_video_frame, get_source_thumbnail, and get_storyboard wait up to about 90 seconds when an upload is converting or a render is taking longer than the upstream request. If the image is still unavailable, the tool returns a retryable error with code: "thumbnail_not_ready" and status: "processing" (conversion) or status: "rendering" (render). Call the same tool again with the same arguments to keep waiting; a render retry does not start a second render. Other upstream failures return code: "thumbnail_fetch_failed" with a signed URL to fetch manually. GIF and MP4 requests return a URL without waiting for the image.

get_clip_preview

Get an MP4 preview from a clip’s rendered playback timeline. The tool waits up to a minute for the render and returns a signed url rather than inline video content. When status is ready, you can download the URL immediately. When status is rendering, call get_clip_preview again with the same arguments to keep waiting; this reuses the render instead of starting another one. A failed render returns a tool error with code: "preview_render_failed", the upstream httpStatus, and a message. If the render status cannot be checked, the result has a url but no status; fetching that URL may start the render and return HTTP 408 while it is still running.

string

required

Video ID

string

required

Clip ID

integer

Preview offset in ms on the clip’s playback timeline (default 0)

integer

Preview duration in ms (default 5000, range 500–30000)

integer

1, 2, 5, 10, or 30 (default 30)

integer

Output width in pixels. Defaults to 320. The preview keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels. Derived from the video’s aspect ratio when omitted.

boolean

Suggest a download disposition on the signed URL

get_video_frame

Get a rendered frame from an entire video’s playback timeline. It returns the same processing results and accepts the same frame format and sizing options as get_clip_frame.

string

required

Video ID

enum<string>

jpg (default), png, webp, or gif

integer

Frame offset in ms from the video’s playback start (cumulative across clips, cuts applied)

integer

Duration in ms when format is gif

integer

Output width in pixels. Defaults to 320 (small, cheap in LLM tokens). The frame keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels. Derived from the video’s aspect ratio when omitted.

get_video_preview

Get an MP4 preview from an entire video’s rendered playback timeline. The tool waits up to a minute for the render and returns a signed url rather than inline video content. When status is ready, you can download the URL immediately. When status is rendering, call get_video_preview again with the same arguments to keep waiting; this reuses the render instead of starting another one. A failed render returns a tool error with code: "preview_render_failed", the upstream httpStatus, and a message. If the render status cannot be checked, the result has a url but no status; fetching that URL may start the render and return HTTP 408 while it is still running.

string

required

Video ID

integer

Preview offset in ms from the video’s playback start (cumulative across clips, cuts applied)

integer

Preview duration in ms (default 5000, range 500–30000)

integer

1, 2, 5, 10, or 30 (default 30)

integer

Output width in pixels. Defaults to 320. The preview keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels. Derived from the video’s aspect ratio when omitted.

get_storyboard

Get a fixed 4×4 WebP storyboard whose 16 tiles are sampled evenly across the requested window (durationMs/16 apart; every 5 seconds for the default 80s window).

Returns inline WebP image content the model can inspect, plus JSON with the signed url, columns, rows, and intervalMs. Tile i (row-major) shows the frame at startTimeMs + i * intervalMs.
Pass videoId alone for the full story, videoId with clipId for a rendered clip, or sourceId alone for a streaming upload.

Storyboards for videos and their clips are available outside your workspace when the video has an ungated public link. A public or embed-only playlist does not bypass the video’s own private link, password, or email gate.

string

Required for a story or clip. Video/story ID

string

Clip/scene ID; requires videoId

string

Required for a streaming upload. Source ID; cannot be combined with videoId or clipId

integer

Storyboard window start in ms on the selected target’s timeline (default 0): the video’s cumulative playback timeline, the clip’s playback timeline, or the raw source file.

integer

Window duration in ms (default 80,000ms). Pass the target’s full duration to sample the whole video end to end.

Tile count, dimensions, and format are fixed; the sampling interval follows from durationMs.

set_video_thumbnail

Set a video’s thumbnail. Two modes, mutually exclusive:

Uploaded image: call create_source with kind: "image", HTTP PUT the image bytes to the returned uploadUrl, then pass the sourceId here.
Frame from the video: pass inpointMs, a time on the video’s playback timeline (cuts applied, cumulative across clips). Inspect candidate frames first with get_video_frame, passing the same value as startTimeMs.

Setting one mode clears the other. A picked frame leaves customThumbnailURL null — verify it through thumbnailInpointMs in the video’s settings from get_video.

string

required

Video ID

string

Uploaded image source ID

integer

Thumbnail frame time in ms

remove_video_thumbnail

Remove a video’s custom thumbnail (uploaded image or picked frame) and revert to the default auto-generated thumbnail.

string

required

Video ID

get_source_thumbnail

Get a thumbnail of a specific source recording. For jpg, png, or webp, returns inline image content plus a signed URL; for gif or mp4, returns the signed URL only. Pass videoId with clipId for a source on a clip, or sourceId alone for a source in your workspace that isn’t on any clip yet.

string

Video ID; pass together with clipId

string

Clip ID using the source; pass together with videoId

string

required

Source recording ID

enum<string>

jpg, png, webp, gif, or mp4

integer

Frame offset in ms from the raw source file’s start — no clip cuts apply

integer

Duration of the animated preview (gif/mp4 only)

integer

Output width in pixels. Defaults to 320 (small, cheap in LLM tokens). The thumbnail keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels. Derived from the video’s aspect ratio when omitted.

get_source_waveform

Get the waveform data for a source recording’s audio track. Pass videoId with clipId for a source on a clip, or sourceId alone for a source in your workspace that isn’t on any clip yet.

string

Video ID; pass together with clipId

string

Clip ID using the source; pass together with videoId

string

required

Source recording ID

get_transcript

Transcript for the clip (cuts applied — what the viewer hears). Word indices are stable identifiers for cut_clip_by_transcript; they don’t shift when cuts change. To see words that were cut out, clear the cuts first (update_clip with cuts: []) — cuts are always undoable. Each word includes breakAfter and keepWithNext. breakAfter: true forces the next word into a new subtitle block. keepWithNext: true keeps the word’s block together with the next word across punctuation and pauses, but the lines-per-block limit still applies and breakAfter takes priority. These fields are also returned by the public API’s clip transcript endpoint. For a long clip, pass startTimeMs and endTimeMs to read its transcript in windows. A word belongs to the window containing its start time; adjacent windows don’t repeat words. Omit both to get the whole transcript.

string

required

Video ID

string

required

Clip ID

integer

First time to include, in ms on the clip’s playback timeline (default: clip start). Must be at least 0.

integer

First time to exclude, in ms on the clip’s playback timeline (default: clip end). Must be greater than startTimeMs.

update_transcript_words

Fix what the transcript says. Each edit addresses one word by its index from get_transcript and sets text (the corrected wording, which also unhides the word), hidden (whether the word shows in captions and subtitles), breakAfter (whether a new subtitle block starts after the word) or keepWithNext (whether the word’s subtitle block stays together with the next word where punctuation or a pause would split it). You can send text with hidden: false, but not with hidden: true; breakAfter and keepWithNext go on their own. Returns the edited words in their new state.

Corrections apply to the transcript, captions and subtitles together. The audio and the clip’s timing are untouched — use cut_clip_by_transcript to actually remove spoken words.
Send every correction for a clip in one call: at most one edit per word, and at most 100 words.
Hiding or showing a word leaves its wording alone, so the two can be combined in any order.
To join two subtitle blocks, set keepWithNext: true on the last word of the first block. If that word has breakAfter: true, first clear it with breakAfter: false in a separate call: you cannot change both attributes or send two edits for the same word in one batch. The lines-per-block limit still applies, and breakAfter wins over keepWithNext.

A batch is applied atomically, so a call never changes only some of its words. An error does not by itself mean nothing changed — the words can land and a later step still fail — so treat the outcome as either fully applied or not applied at all. Every edit assigns a word outright, so re-sending the identical call is safe and settles it.

string

required

Video ID

string

required

Clip ID

object[]

required

Array of {index, text}, {index, hidden}, {index, breakAfter} or {index, keepWithNext} edits, at most 100. Indices come from get_transcript; a word that is currently cut out of the clip can’t be edited.

Show properties

integer

required

Index of the word to edit, from get_transcript.

string

Corrected text for the word. Must not be empty — use hidden: true to drop a word from captions.

boolean

true hides the word from captions and subtitles (the audio is untouched); false shows it again and can be sent with corrected text.

boolean

true starts a new subtitle block after this word; false removes the break.

boolean

true keeps this word’s subtitle block together with the next word across punctuation and pauses; false restores the automatic split.

get_clip_filters

Get the color filters on a clip’s camera and screen recordings: the matching preset (or custom), exposure, contrast, saturation, temperature, tint, and LUT. camera or screen is null when the clip has no such recording. These are the editor’s Style → Filters settings.

string

required

Video ID

string

required

Clip ID

set_clip_filters

Color-grade a clip’s camera, screen recording, or uploaded footage. Pass camera, screen, or both. Filters are per clip: to grade a whole video, call this for each clip from list_clips. Check the result with get_clip_frame. Setting a filter for a recording the clip does not have returns an error. Only supplied fields change. A preset replaces the entire filter, including the LUT, before other supplied fields adjust it. Without a preset, fields adjust the current filter. Pass null for a recording’s filter to remove it, or lut: null to remove only its LUT. The call returns the filters after the change.

string

required

Video ID

string

required

Clip ID

object | null

Camera filter. Uses the same fields as screen below.

object | null

Screen recording or uploaded-video filter.

Show properties

enum<string>

none, warm, cool, crisp, fade, or mono. Camera and uploaded footage also support golden-hour, vivid, noir, dreamy, and night; these are not available for screen recordings.

number

Brightness, -1 to 1. Zero is unchanged; ±1 is two stops.

number

Contrast, -1 to 1. Zero is unchanged.

number

Color intensity, -1 (black and white) to 1. Zero is unchanged.

number

White balance, -1 (cooler) to 1 (warmer). Zero is unchanged.

number

Green/magenta balance, -1 (more green) to 1 (more magenta). Zero is unchanged.

object | null

{id, intensity}: a built-in LUT ID or a library item ID from list_library with type: "lut". Intensity is 0–1; omitted intensity keeps the current value for the same LUT, otherwise defaults to 1. Upload your own with create_source and save it with add_library_item.

{
  "videoId": "vid_abc123",
  "clipId": "clp_1",
  "camera": {"preset": "warm", "exposure": 0.2},
  "screen": {"saturation": -0.1}
}

Filters appear in the editor and in exports rendered by the new render engine.

Getting Started

Guides

MCP Tools

API Reference

Webhooks

upload_clip

list_clips

get_clip

update_clip

delete_clip

duplicate_clip

reorder_clip

cut_clip

cut_clip_by_transcript

get_silences

remove_fillers

remove_silences

list_sources

get_clip_frame

get_clip_preview

get_video_frame

get_video_preview

get_storyboard

set_video_thumbnail

remove_video_thumbnail

get_source_thumbnail

get_source_waveform

get_transcript

update_transcript_words

get_clip_filters

set_clip_filters

​upload_clip

​list_clips

​get_clip

​update_clip

​delete_clip

​duplicate_clip

​reorder_clip

​cut_clip

​cut_clip_by_transcript

​get_silences

​remove_fillers

​remove_silences

​list_sources

​get_clip_frame

​get_clip_preview

​get_video_frame

​get_video_preview

​get_storyboard

​set_video_thumbnail

​remove_video_thumbnail

​get_source_thumbnail

​get_source_waveform

​get_transcript

​update_transcript_words

​get_clip_filters

​set_clip_filters

upload_clip

list_clips

get_clip

update_clip

delete_clip

duplicate_clip

reorder_clip

cut_clip

cut_clip_by_transcript

get_silences

remove_fillers

remove_silences

list_sources

get_clip_frame

get_clip_preview

get_video_frame

get_video_preview

get_storyboard

set_video_thumbnail

remove_video_thumbnail

get_source_thumbnail

get_source_waveform

get_transcript

update_transcript_words

get_clip_filters

set_clip_filters