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.

​

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.

​

list_clips

List clips in a video, ordered by their position.

​

get_clip

Get a single clip’s details.

​

update_clip

Update a clip’s name, ordering, cuts, background, transition, Studio Sound opt-out, audio volumes, or animated cursor. 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.

​

delete_clip

Remove a clip from its video.

​

duplicate_clip

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

​

reorder_clip

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

​

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: [].

​

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.

​

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.

​

remove_fillers

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

​

remove_silences

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

​

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.

​

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). While the video is still uploading or converting, the tool returns a result with code: "thumbnail_not_ready" and status: "processing" instead of an image — retry once the video finishes processing. Other upstream failures return code: "thumbnail_fetch_failed" with a signed URL to fetch manually.

​

get_clip_preview

Get an MP4 preview from a clip’s rendered playback timeline. It returns a signed URL rather than inline video content.

​

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.

​

get_video_preview

Get an MP4 preview from an entire video’s rendered playback timeline. It returns a signed URL rather than inline video content.

​

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

​

remove_video_thumbnail

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

​

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.

​

get_source_waveform

Get the waveform data for a source recording’s audio track.

​

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.

​

update_transcript_words

Fix what the transcript says. Each edit addresses one word by its index from get_transcript and sets either text (the corrected wording, which also unhides the word) or hidden (whether the word shows in captions and subtitles) — never both. 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.

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.