list_videos
List videos with pagination support. By default this is your own library (the My videos tab): videos you created or were invited to. Passscope: "workspace" for every video shared with your workspace (the Workspace videos tab), including videos other members made.
Filter videos by playlist. Outside your workspace, the playlist must have an ungated public link
Filter videos by tag IDs, comma-separated. Multiple tags are combined with AND. Ignored when
playlistId is setpersonal (default) or workspace. With workspace, videos come most recently updated first and archived videos are removed after a page is read, so a page can be shorter than limit; keep paging while nextCursor is set. workspace can’t be combined with playlistId or tagIdssearch_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.
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.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.Include the transcript as plain text, without word timings, when you have workspace access or the owner has made it public. Use
get_transcript for word timings.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.
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. layouts also returns each clip’s layoutSceneType, so you can tell a camera-only clip from a camera-and-screen clip whose layout hides the screen.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. Each word also reports breakAfter and keepWithNext, so you can inspect forced subtitle breaks and keep-together edits before changing them with update_transcript_words.
create_video
Create a new video. From an uploaded file, callcreate_source first (kind: "video"), PUT the bytes to the returned uploadUrl, then pass the sourceId here and it becomes the new video’s first clip. Without sourceId the video is empty, as New video in Tella makes: add clips with upload_clip or create_clip (type: "motion").
Returns the new video’s id, name, clipIds, editorRevision and links, plus each setting you passed as it was saved (password is never returned).
Also accepts every setting of update_video — name, description, playbackRate, the caption settings, linkScope, password, and so on — so a video can be created fully configured in one call. As with update_video, password is not available in ChatGPT or other OpenAI-hosted clients — see Link passwords in ChatGPT.
update_video
Update video metadata and settings. Returns the video’sid, editorRevision and updatedAt, plus each field you passed as it was saved (password is never returned). Call get_video for everything else.
Speed the share page’s player starts at (0.5-2.0); viewers can change it. It doesn’t change the video’s length, the editor preview or exports. For a faster or slower file, use
export_video’s speed.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.Normalized subtitle
{ x, y } coordinates from 0 to 1, or null for automatic placement; used if subtitles are enabled on the videoSubtitle font family — one of Tella’s catalog fonts (the list the editor’s font picker offers), or the video’s current family to keep an uploaded font.
get_video reports the family the subtitles render withFont weight on the variable-font axis, 100 to 1000, clamped to the range the family supports. On its own it re-weights the video’s current font
Exact subtitle size, 40 to 200 — the editor’s Size slider.
captionSize is the same setting in buckets (small 40, medium 64, large 80); pass one or the other, not bothPassword for protected videos. Not available in ChatGPT or other OpenAI-hosted clients — see Link passwords in ChatGPT.
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.Studio Sound level, matching the Studio Voice dropdown in the editor’s Audio panel:
off, low, or high. low and high turn Studio Sound on and regenerate the enhanced audio when the level changes; off turns it off. Passing studioSound with a conflicting value (for example false with high) returns an error. get_video reports the current level.Eye contact correction, the Eye contact switch in the editor’s Adjust panel: AI redirects the speaker’s gaze to the lens in every camera recording.
true starts preparing each camera in the background, which takes about as long as the recording; false restores the natural look. Screen recordings and uploaded videos are never changed, and a video without a camera recording returns an error. The response shows the switch as asked for with status: "processing"; get_video reports settings.eyeContact (enabled, status, cameras, camerasReady) until it is ready.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.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.Blur fast zoom, pan, and cursor movement. Videos created with
create_video start with this off — pass true to enable it.Motion blur strength, matching the editor’s Motion blur slider: 0.1 (subtle) to 2 (strong), with 1 the default. Setting it turns motion blur on; passing it with
motionBlur: false returns an error.Shrink camera bubbles while a zoom is active. Videos created with
create_video start with this off — pass true to enable it.How layout transitions animate. One of
gentlest, gentle, relaxed, smooth, moderate, brisk, focused, snappy, punchy, snappiest. Changing it leaves zooms as they were: when zooms have no zoomAnimationStyle of their own, they keep the previous style.How zooms ease in, out, and between each other, independent of
layoutAnimationStyle. Same values as layoutAnimationStyle.Animated cursor settings. Provide any fields you want to change:
style (mac, macTahoe, macGoldenGate, windows, or touch), size (0.5–6), smoothing, tilt, tiltStrength (0–2), clickRipple, hideWhenInactive, or returnToStart. Omitted nested fields keep their current values.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.The video’s own call-to-action button on its share page, as
{ label, url }. The label is up to 100 characters and the url must start with https:// or http://; both are trimmed. Pass null to remove the video’s own button, after which the workspace’s default button (Settings → CTA button) shows if there is one. This never changes the workspace default.A second button next to
callToAction, with the same shape and rules. Pass null to remove it.true hides every call-to-action button on the share page, the workspace defaults included. false shows them again.Canvas size in pixels as
{ width, height } (each 16–1920). This is the layout canvas, not the output resolution: for a 4K file, call export_video with resolution: "4k". Changing it remaps every clip and section layout to a ratio-appropriate equivalent — the same transform as switching size in the editor’s canvas size menu (the ratio control in the toolbar under the preview, or in the Layout panel header). 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.Auto in the editor’s canvas size menu.
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. They also return callToAction, secondaryCallToAction and callToActionsHidden, plus the workspace defaults as workspaceCallToAction and workspaceSecondaryCallToAction: callToAction is null when the video has no button of its own, even if the workspace default shows on its share page.
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.save_subtitle_preset
Save a subtitle look as a personal preset, like the editor’s “Save as preset”. PassvideoId to snapshot that video’s current subtitles (style, font, weight, size, position, grouping and lines per block), captionStyle to build one from scratch on the style’s defaults, or both — explicit caption fields, including the font, size and lines per block, override the video’s. The preset then shows up in list_subtitle_presets (scope personal) and in the editor’s Subtitles panel, and can be applied to other videos with apply_subtitle_preset.
Preset name, as shown in the editor. Defaults to the matching built-in’s name, numbered past any saved preset already using it
Subtitle style, in the same shape as
update_video_settings. Required without videoId; with it, replaces the video’s styleNormalized
{x, y} position, or null for automatic placement. Defaults to the video’s, or automaticFont weight, 100 to 1000, clamped to the family’s range. Defaults to the font’s current weight
Exact subtitle size, 40 to 200. Defaults to the video’s, or the style’s default. Pass this or
captionSize, not bothremove_subtitle_language
Remove a translated subtitle track from a video. You need edit access to the video. The original subtitles stay unchanged, but viewers can no longer select the removed language in the player. ReturnssourceLanguageCode and the video’s remaining languages, including each track’s status, untranslatedSentences, and totalSentences.
get_captions_file
Get ready captions as SRT or WebVTT text. Returnsformat, fileName, and content. Cue times are whole-video playback time with cuts applied; clip editing tools take clip playback time, so use get_transcript to place edits at a spoken line.
generate_document
Start writing a document from a video’s transcript, the same way the Ask tab on the video’s share page does: a summary, step-by-step guide, meeting notes, FAQ or anything else the prompt asks for. Returns adocument with status: pending right away; poll get_document until it is completed (most finish within a minute) and read the Markdown in content. Its first # heading, when present, is the title. The document uses only what was said in the video and follows the transcript’s language unless the prompt asks for another.
Refused when documentGenerationEnabled is off for the video; a video with no transcript ends failed. Limited to 20 documents per minute per workspace. Documents are kept for 7 days.
What to write, e.g. “Write a step-by-step guide from this video”. Up to 2000 characters.
get_document
Get a document started withgenerate_document. While document.status is pending, wait a few seconds and call again. On completed, document.content holds the Markdown; on failed, document.error says why.
delete_video
Delete a video (moves to trash).duplicate_video
Create a copy of a video. Supports trimming to extract a time range or specific chapter. Returns the copy’sid, name, clipIds, editorRevision and links.
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.
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)Playback speed —
0.5, 0.75, 0.8, 0.9, 1, 1.1, 1.2, 1.25, 1.3, 1.35, 1.5, 1.7, 1.75, 2, or 2.5. Any speed other than 1 requires the video creator’s paid plan and is not available during a free trial.get_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.
get_live_preview_link
Get a link to a video’s live preview: a player of the editor’s preview that shows every saved edit (yours, the user’s, another agent’s) a moment later, without re-rendering. Embed it or hand it to the user so they can watch the video change while you edit it. Requires edit access to the video. The link plays for whoever opens it, without signing in, untilexpiresAt (24 hours later), so share it only with the user. Call the tool again for a fresh link.
get_recording_link
Start a new recording: get a link the user opens to record a new clip with their camera, microphone and screen. The clip is added at the end of the video. Requires edit access to the video. The link opens the user’s own recorder: the browser, or the Tella Mac or Windows app when that’s where they record. A browser recording ends on a page that sends them back to you. Ask the user to tell you when they’re done, then read the new clip withlist_clips. For a new video, call create_video without sourceId first and pass its ID.
add_collaborator_to_video
Add a collaborator to a video. The user must be a member of your workspace.update_collaborator_on_video
Change a collaborator’s role on a video.remove_collaborator_from_video
Remove a collaborator from a video.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.