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 [], which restores the footage; items cut_clip deleted with their footage stay deleted.

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, camera framing, 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?, shaderGradientPreset?}

. type is one of solid, image, video, gradient, shaderGradient, ambient. ambient fills the background with the clip’s screen recording, heavily blurred, while the screen is shown, and with its camera otherwise. shaderGradient is an animated gradient chosen by shaderGradientPreset. 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, shaderGradient, ambient. ambient takes no other fields.

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

string

Animated gradient preset name from list_backgrounds, such as Halo. Required when type = ‘shaderGradient’.

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 and 0 are no-ops and any other 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 and 0 are no-ops and any other 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.

boolean

Mirror (flip horizontally) this clip’s camera, like the editor’s Mirror camera. Applies to this clip only; set it on every clip to mirror the whole video. Errors when the clip has no camera.

object | null

{xPct, yPct} (0–100): which part of the camera recording stays in view when a layout’s camera frame is a different shape than the recording, like the focus point in the editor’s Crop → Adjust camera. 0 keeps the left/top edge, 50 the middle, 100 the right/bottom edge. Measured on the unmirrored recording after cameraCrop. Pass null to reset it to the middle.

object | null

{top, right, bottom, left}: pixels removed from each edge of the unmirrored camera recording (list_sources gives its dimensions). Crop tighter to make the presenter larger in the frame. Pass null to remove the crop.

boolean

Pan the camera to keep the presenter’s face centered as they move, like the editor’s Keep face centered. While it’s on it takes over from cameraFocusPoint. Turning it on errors when the camera has no face detections (older recordings); set cameraFocusPoint instead.

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), snake or glass (a liquid glass rim). snake and glass keep the clip’s current settings for that style, 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 and mirrorCamera, cameraFocusPoint, cameraCrop and keepCameraFaceCentered when it has a camera. The camera framing fields reframe the presenter inside the camera frame without changing the layout or where the camera sits and how big it is. They apply to every layout in the clip, like the editor’s All layouts in this clip: a layout that had its own camera crop or focus point follows the clip again. Set them on each clip to reframe the whole video.

{ "videoId": "vid_…", "clipId": "cl_…", "keepCameraFaceCentered": true }

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

split_clip

Split a clip in two at a time on its playback timeline, like the editor’s split at the playhead. The clip keeps everything before atMs, and a new clip inserted right after it continues from there. Each cut, layout, zoom, blur, highlight and overlay goes to the part it sits on. One that spans atMs is split too: each part keeps its side, and a video, audio or sound effect overlay keeps playing in the second clip from where the first stopped. Both parts must play for at least 200 ms. Returns both clips in playback order; the first keeps the original clip’s id.

string

required

Video ID

string

required

Clip ID to split

integer

required

Where to split, in ms on the clip’s playback timeline. At least 200 ms from either end of the 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. Zooms, blurs, highlights and overlays (text, images, media, sound effects) placed entirely on footage the cut removes are deleted with it; clearing the cuts later does not bring them back. 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. Zooms, blurs, highlights and overlays (text, images, media, sound effects) placed entirely on footage the cut removes are deleted with it; clearing the cuts later does not bring them back.

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.

get_audio_levels

Measure the peak loudness of a clip’s voice track over a time range. Use this to locate a breath, click, or sound the transcript misses, or check audio left at a cut without downloading the source. Times use the clip’s playback timeline, with cuts applied, matching get_transcript and get_silences. This measures the voice track, not the full mix with background music and sound effects.

string

required

Video ID

string

required

Clip ID

number

required

Range start in ms on the clip’s playback timeline. Must be at least 0.

number

required

Range end in ms on the clip’s playback timeline. Must be greater than startTimeMs.

number

Width of each level step in ms (default 10, minimum 5). A range can contain at most 12,000 steps; shorten the range or increase stepMs for longer clips.

The result includes startTimeMs, stepMs, resolutionMs, and levelsDb. Each entry in levelsDb is the peak level in dBFS for a step starting at startTimeMs + index * stepMs: 0 is full scale, more negative values are quieter, and null means there is no audio for that step. The clip must have a voice track and a ready waveform.

Levels come from stored waveform buckets, typically about 5 ms long. resolutionMs reports that bucket length. A step within this distance of a cut can include a little cut audio, so don’t treat it as an exact sound boundary.

You can also read these levels through the REST API with GET /v1/videos/{id}/clips/{clipId}/audio-levels, using startTimeMs, endTimeMs, and optional stepMs query parameters.

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 (range 1–1920, default 320). The frame keeps the video’s aspect ratio.

integer

Output height in pixels (range 1–1920). Derived from the video’s aspect ratio when omitted.

boolean

Suggest a download disposition on the signed URL

boolean

Draw the video’s captions, as an export with subtitles does. Defaults to false, which leaves captions out. Pass true to check how captions look

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). If the frame needs a presenter cut-out that is still rendering, the retryable error uses the same code: "thumbnail_not_ready" with status: "preparing_cutout". Its message includes the cut-out’s progress percentage. This can happen with overlays behind the presenter, and long clips can take a few minutes. The cut-out keeps rendering after the call returns. Call the same tool again with the same arguments to keep waiting; a render retry does not start a second render. If the image is still unavailable after about 3 minutes in total, stop retrying. 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. The MP4 includes the audio, so you can download it to hear how a cut sounds, for example by extracting that time range’s audio with ffmpeg. 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, for about 3 minutes in total; 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 (range 1–1920). Defaults to 320. The preview keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels (range 1–1920). Derived from the video’s aspect ratio when omitted.

boolean

Suggest a download disposition on the signed URL

boolean

Draw the video’s captions, as an export with subtitles does. Defaults to false, which leaves captions out. Pass true to check how captions look

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 (range 1–1920). 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 (range 1–1920). Derived from the video’s aspect ratio when omitted.

boolean

Draw the video’s captions, as an export with subtitles does. Defaults to false, which leaves captions out. Pass true to check how captions look

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. The MP4 includes the audio, so you can download it to hear how a cut sounds, for example by extracting that time range’s audio with ffmpeg. 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, for about 3 minutes in total; 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 (range 1–1920). Defaults to 320. The preview keeps the video’s aspect ratio, so omit height to have it derived automatically.

integer

Output height in pixels (range 1–1920). Derived from the video’s aspect ratio when omitted.

boolean

Draw the video’s captions, as an export with subtitles does. Defaults to false, which leaves captions out. Pass true to check how captions look

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.

get_filmstrip

Get several rendered frames of a video, of one clip, or of a source (any uploaded video, such as an attachment) as one JPEG grid, rendered in one render. Each tile is labelled with its time (m:ss.cc). Use it for an overview, and to compare moments side by side: the frames just before, at and just after a cut, the steps of a transition, or a check after an edit.

Pass videoId alone, videoId with clipId, or sourceId alone.
Times are on the video’s playback timeline (cuts applied, cumulative across clips), on the clip’s playback timeline when clipId is given, or on the source’s own timeline.
Pick the frames one way: timesMs (2–24 exact times, shown in the order given); a range with startTimeMs, endTimeMs (excluded) and intervalMs; or neither, for 16 frames spread evenly over the range (the whole video or clip by default).
Returns inline JPEG image content plus JSON with columns, rows, tileWidth, tileHeight and tiles: one entry per tile, row-major, with its timeMs and, for a video, the clipId and clipTimeMs it falls in.
Captions are left out unless you pass subtitles: true. It needs videoId: a source has no captions.
At most 24 frames per call. For one moment at full size, such as small text, use get_video_frame (get_source_thumbnail for a source); for motion, audio or lip sync, use get_video_preview.

It waits and retries like get_video_frame (see above). It does everything get_storyboard does, with labelled tiles and exact times; get_storyboard stays for existing clients. This tool is MCP-only: REST clients fetch frames one at a time from the thumbnail endpoints, or a storyboard.

string

Video ID. Pass alone, or with clipId for one clip

string

Clip ID. Times are then on this clip’s playback timeline

string

Source ID. Pass alone, without videoId or clipId

integer[]

2–24 exact frame times in ms. Cannot be combined with startTimeMs, endTimeMs or intervalMs

integer

Range start in ms (default 0)

integer

Range end in ms, excluded (default: the end of the video, clip or source)

integer

Spacing between frames in the range. Omit for 16 frames spread evenly

integer

Tile width in pixels, 160–640 (default 320). Height follows the video’s aspect ratio

integer

Tiles per row (default: as many as fit in about 1,500px)

boolean

Draw the video’s captions, as an export with subtitles does. Defaults to false, which leaves captions out. Pass true to check how captions look

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 (range 1–1920). 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 (range 1–1920). 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. Returns the BBC audiowaveform format for the whole source in source time, without clip cuts applied. Use this for custom waveform visualizations; use get_audio_levels to measure loudness over part of a clip’s playback timeline.

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, pass includeCut: true (below). Each word includes hidden, breakAfter, and keepWithNext only when they are true. Treat an absent flag as false. hidden: true hides the word from captions and subtitles without changing the audio. 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. This omission applies only to MCP get_transcript. The public API’s clip transcript endpoint, update_transcript_words, and get_timeline still return explicit boolean values for these flags. 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. Pass view: "text" to get every word with its index as plain text, about a seventh of the size of the words: one sentence per line, starting with the sentence’s start time, then each word as index:word ([1:02.5] 12:Hello 13:there.). It suits reading a whole long clip, such as looking for retakes and repeated sentences, and its indices go straight into cut_clip_by_transcript. Read the words view for a stretch where you need exact word times, such as placing something at a word. Pass view: "sentences" to get one row per sentence instead: firstIndex, lastIndex, startTimeMs, endTimeMs and text, about a quarter of the size of the words. It suits finding where something is said. A clip you just recorded has no words until its recording is transcribed. Until then the call fails and says the clip is still being transcribed; wait about 30 seconds and call it again. A clip whose recording has no voice returns an empty transcript. To read a source that isn’t on any clip yet, such as an imported video or a chat attachment, pass sourceId alone instead of videoId and clipId. You get the source’s whole transcript in source time, with no cuts applied; time windows, view: "text" and view: "sentences" work the same way. The call fails while the source is still being transcribed, so wait until get_source reports it ready. In the public API, the same transcript is at GET /v1/sources/{sourceId}/transcript.

string

Video ID; pass together with clipId

string

Clip ID; pass together with videoId

string

Source ID, instead of videoId and clipId. Times are then in source time

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.

string

words (default), text or sentences. A time window cuts sentences at its edges.

boolean

Also return the words cuts removed. Each word then has sourceStartTimeMs and sourceEndTimeMs, its times in the clip’s source recording; kept words also have their playback startTimeMs and endTimeMs, and cut words have cut: true instead. The time window filters on source times. Words view only.

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 at most one edit per word and at most 100 words per call; split a longer rewrite into several calls.
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

split_clip

reorder_clip

cut_clip

cut_clip_by_transcript

get_silences

get_audio_levels

remove_fillers

remove_silences

list_sources

get_clip_frame

get_clip_preview

get_video_frame

get_video_preview

get_storyboard

get_filmstrip

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

​split_clip

​reorder_clip

​cut_clip

​cut_clip_by_transcript

​get_silences

​get_audio_levels

​remove_fillers

​remove_silences

​list_sources

​get_clip_frame

​get_clip_preview

​get_video_frame

​get_video_preview

​get_storyboard

​get_filmstrip

​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

split_clip

reorder_clip

cut_clip

cut_clip_by_transcript

get_silences

get_audio_levels

remove_fillers

remove_silences

list_sources

get_clip_frame

get_clip_preview

get_video_frame

get_video_preview

get_storyboard

get_filmstrip

set_video_thumbnail

remove_video_thumbnail

get_source_thumbnail

get_source_waveform

get_transcript

update_transcript_words

get_clip_filters

set_clip_filters