list_videos
List all videos in your workspace with pagination support.string
Pagination cursor from previous response
integer
Items per page (1-100, default: 20)
string
Filter videos by playlist. Outside your workspace, the playlist must have an ungated public link
string
Filter videos by tag IDs, comma-separated. Multiple tags are combined with AND. Ignored when
playlistId is setsearch_videos
Search your direct video library by title or indexed transcript sentences. UsesearchIn to restrict the search to title or transcript; otherwise title results come before transcript results.
Results include video summaries, plain-text snippets, matched tokens, and cursor pagination. Transcript matches also carry startSeconds and endSeconds, so you can jump straight to the moment a phrase was spoken. To keep latency predictable, each transcript search considers the 2,000 highest-relevance matching sentences.
string
required
Search text, 1-200 characters
enum<string>
all, title, or transcript (default: all)integer
Results per page, 1-100 (default: 20). An upper bound, not a guarantee: a page can come back shorter once results the caller cannot see are removed. Keep paging while
hasMore is true.string
Opaque cursor returned by the previous page
get_video
Get video information. Returns summary fields by default. Use include flags for additional data. You can also read a video outside your workspace when it has an ungated public link. Adding a video to a public or embed-only playlist does not bypass the video’s own private link, password, or email gate. Public-access responses omit private editor metadata and exports. They include the transcript only when the owner has made transcripts available, and include view count and publish date only when those details are visible to viewers.string
required
Video ID
boolean
Include transcript text when you have workspace access or the owner has made it public
boolean
Include chapter markers
boolean
Include thumbnail URLs
boolean
Include export status when you have workspace access
get_timeline
Get an ordered outline of a video’s complete timeline in one call. Start here when reading or editing a video: the default response identifies every clip, its position and playback duration, and counts its cuts, layouts, effects, overlays, sound effects, and transcript words. Useinclude only for the details needed next, instead of calling every per-clip list tool.
The complete outline is returned on every call. clipIds limits only details.clips, so an agent can inspect the whole video while fetching detailed data for one or two relevant clips.
string
required
Video ID
enum<string>[]
Non-empty array of detail categories:
settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, or words. Pass all for the complete edit state.string[]
Non-empty array of clip IDs to include in
details.clips. The ordered clip outline is never filtered.- Call
get_timelinewith onlyvideoIdto inspect the compact outline. - Pick relevant clips from their content counts.
- Call it again with
clipIdsand the requiredincludecategories, such aszoomsorwords. - Apply edits with the returned stable IDs, then fetch the affected details again to verify.
timelineStartMs is the clip’s start on the complete video timeline. Raw cut definitions use the source recording’s timeline, matching get_clip.
Transcript availability is explicit: transcriptWords and requested transcript details are null while transcription is processing, failed, or unreadable; a ready clip with no speech returns 0 and an empty array. Hidden words remain in words with stable indices.
create_video
Create a new video from an uploaded source. Callcreate_source first (kind: "video"), PUT the bytes to the returned uploadUrl, then pass the sourceId here — it becomes the new video’s first clip.
string
required
Source ID from
create_source (kind: "video")update_video — name, description, playbackRate, the caption settings, linkScope, password, and so on — so a video can be created fully configured in one call.
update_video
Update video metadata and settings.string
required
Video ID
string
Video title
string
Video description
number
Default playback speed (0.5-2.0)
boolean
Show subtitles to viewers by default
boolean
Allow viewers to enable subtitles
object
Subtitle style, used if subtitles are enabled on the video. Pick a style by
name and pass its required colors; fields from other styles are rejected. Colors accept #RRGGBB or #RRGGBBAA.enum<string>
Subtitle size (
small, medium, or large), used if subtitles are enabled on the videoenum<string>
Subtitle grouping (
chunked or singleWord), used if subtitles are enabled on the videoobject | null
Normalized subtitle
{ x, y } coordinates from 0 to 1, or null for automatic placement; used if subtitles are enabled on the videoboolean
Show transcript tab
boolean
Allow comments
boolean
Allow downloads
enum<string>
Access level —
public, private, password, or embedonlystring
Password for protected videos
boolean
Allow search engine indexing
boolean
Studio Sound (AI audio enhancement) master switch. Enabling it also starts generating the enhanced audio tracks in the background; playback and exports fall back to raw audio until they are ready. Individual clips can opt out via
update_clip’s studioSound.number
Volume of the microphone (webcam) audio across the whole video. 1 is the recorded level, 0 mutes it, 2 doubles it. Clips that set their own
microphoneVolume keep it — change those with update_clip.number
Volume of the system/screen audio across the whole video — everything that is not microphone audio. Same 0–2 range, and likewise overridable per clip with
update_clip.boolean
Blur fast zoom, pan, and cursor movement. Videos created with
create_video start with this off — pass true to enable it.boolean
Shrink camera bubbles while a zoom is active. Videos created with
create_video start with this off — pass true to enable it.object
Animated cursor settings. Provide any fields you want to change:
style (mac, macTahoe, macGoldenGate, windows, or touch), size (0.5–6), smoothing, clickRipple, hideWhenInactive, or returnToStart. Omitted nested fields keep their current values.enum<string>
How clips enter from the previous clip —
smooth eases across the change, while hard_cut switches instantly. Individual clips can override this with update_clip’s transition.object
Canvas size in pixels as
{ width, height } (each 16–4096). Changing it remaps every clip and section layout to a ratio-appropriate equivalent — the same transform as switching size in the editor’s Setup → Size. Editor presets: 1920x1080 (16:9), 1920x1200 (16:10), 1440x1080 (4:3), 1080x1080 (1:1), 1080x1350 (4:5), 1080x1920 (9:16). No-op when the video already has the requested size. Setting explicit dimensions takes the video out of Auto ratio.boolean
The editor’s Setup → Size → Auto.
true sizes the canvas from the video’s recording — the first clip with a screen recording, else the first clip’s video or image — with the layout’s padding equal on all sides, and keeps it following the recording as layouts change. When that changes the canvas’s ratio class, layouts are remapped like a dimensions change. false pins the current size. Pass either autoRatio or dimensions, not both. get_video and list_videos report the current mode as autoRatio.get_video and get_timeline with settings included return the current defaultClipTransition under the video’s settings.
list_subtitle_presets
List Tella’s built-in subtitle styles and your saved styles. Each result includes apresetId, name, scope (default or personal), and a captionStyle preview.
Pass a returned presetId to apply_subtitle_preset.
apply_subtitle_preset
Apply a built-in or saved subtitle preset to a video. This changes the subtitle appearance without changing the transcript or enabling subtitles. Built-in presets apply their style, font, weight, and size while preserving the video’s position, grouping, and lines per block. Personal presets restore those saved layout settings too.string
required
Video ID
string
required
Preset ID from
list_subtitle_presetsget_captions_file
Get ready captions as SRT or WebVTT text. Returnsformat, fileName, and content.
string
required
Video ID
enum<string>
srt (default) or vttdelete_video
Delete a video (moves to trash).string
required
Video ID
duplicate_video
Create a copy of a video. Supports trimming to extract a time range or specific chapter.string
required
Video ID to duplicate
string
Name for the duplicate
number
Trim start time in seconds (use with endTime)
number
Trim end time in seconds (use with startTime)
integer
Extract a specific chapter by 0-based index (cannot be combined with startTime/endTime)
export_video
Start a video export. Useget_export_status to poll until the export completes or fails.
Returns an export object. Pass its exportId value to get_export_status.
string
required
Video ID
enum<string>
video (full video, default), clips (one composed file per clip), tracks (camera and screen files per clip with timeline cuts applied), or raw (original recordings without cuts)enum<string>
4k for 4K; omit for defaultenum<string>
Frames per second —
30 or 60boolean
Burn in subtitles
enum<string>
Playback speed —
0.5, 0.75, 1, 1.25, 1.5, 1.75, or 2get_export_status
Get an export’s current status and progress. Poll this afterexport_video until export.status is completed or failed; export.downloadUrl appears when the export is ready.
string
required
Video ID
string
required
The
export.exportId value returned by export_videoadd_collaborator_to_video
Add a collaborator to a video. The user must be a member of your workspace.string
required
Video ID
string
required
Email address of the user to add
enum<string>
required
Role to grant —
editor or viewerupdate_collaborator_on_video
Change a collaborator’s role on a video.string
required
Video ID
string
required
User ID of the collaborator
enum<string>
required
New role —
editor or viewerremove_collaborator_from_video
Remove a collaborator from a video.string
required
Video ID
string
required
User ID of the collaborator to remove
You can’t change the role of, or remove, the video’s Creator —
update_collaborator_on_video and remove_collaborator_from_video reject those calls with a 403. To hand off ownership, use the transfer ownership flow in the app.