> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Videos

> Find, read, configure, export, and share the videos in your workspace.

## list\_videos

List all videos in your workspace with pagination support.

<ParamField path="cursor" type="string">
  Pagination cursor from previous response
</ParamField>

<ParamField path="limit" type="integer">
  Items per page (1-100, default: 20)
</ParamField>

<ParamField path="playlistId" type="string">
  Filter videos by playlist. Outside your workspace, the playlist must have an ungated public link
</ParamField>

<ParamField path="tagIds" type="string">
  Filter videos by tag IDs, comma-separated. Multiple tags are combined with AND. Ignored when `playlistId` is set
</ParamField>

## search\_videos

Search your direct video library by title or indexed transcript sentences. Use `searchIn` 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.

<ParamField path="query" type="string" required>
  Search text, 1-200 characters
</ParamField>

<ParamField path="searchIn" type="enum<string>">
  `all`, `title`, or `transcript` (default: `all`)
</ParamField>

<ParamField path="limit" type="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.
</ParamField>

<ParamField path="cursor" type="string">
  Opaque cursor returned by the previous page
</ParamField>

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

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="includeTranscript" type="boolean">
  Include transcript text when you have workspace access or the owner has made it public
</ParamField>

<ParamField path="includeChapters" type="boolean">
  Include chapter markers
</ParamField>

<ParamField path="includeThumbnails" type="boolean">
  Include thumbnail URLs
</ParamField>

<ParamField path="includeExports" type="boolean">
  Include export status when you have workspace access
</ParamField>

## 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. Use `include` 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.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="include" type="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.
</ParamField>

<ParamField path="clipIds" type="string[]">
  Non-empty array of clip IDs to include in `details.clips`. The ordered clip outline is never filtered.
</ParamField>

**Typical agent flow:**

1. Call `get_timeline` with only `videoId` to inspect the compact outline.
2. Pick relevant clips from their content counts.
3. Call it again with `clipIds` and the required `include` categories, such as `zooms` or `words`.
4. Apply edits with the returned stable IDs, then fetch the affected details again to verify.

All detail times are milliseconds on the clip's playback timeline, with cuts applied. `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. Call `create_source` first (`kind: "video"`), `PUT` the bytes to the returned `uploadUrl`, then pass the `sourceId` here — it becomes the new video's first clip.

<ParamField path="sourceId" type="string" required>
  Source ID from `create_source` (`kind: "video"`)
</ParamField>

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.

## update\_video

Update video metadata and settings.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="name" type="string">
  Video title
</ParamField>

<ParamField path="description" type="string">
  Video description
</ParamField>

<ParamField path="playbackRate" type="number">
  Default playback speed (0.5-2.0)
</ParamField>

<ParamField path="captionsEnabled" type="boolean">
  Show subtitles to viewers by default
</ParamField>

<ParamField path="subtitlesEnabled" type="boolean">
  Allow viewers to enable subtitles
</ParamField>

<ParamField path="captionStyle" type="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`.

  | `name`      | Required fields                                            | Notes                                                                    |
  | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
  | `backdrop`  | `backgroundColor`, `textColor`, `wordLevelHighlights`      | Optional `highlightColor` — omit for the legacy text-opacity progression |
  | `highlight` | `primaryTextColor`, `secondaryTextColor`, `highlightColor` |                                                                          |
  | `mono`      | `textColor`, `highlightColor`                              |                                                                          |
  | `cannes`    | `textColor`, `shadowColor`                                 | Optional `highlightColor`, defaults to `textColor`                       |
  | `classic`   | `textColor`, `outlineColor`                                | Optional `highlightColor`, defaults to `textColor`                       |

  <Expandable title="shared fields">
    <ParamField path="wordLevelHighlights" type="boolean">
      Highlight each spoken word. Required for `backdrop`. On the other styles it is optional and defaults to `true` for `highlight` and `mono`, and to `false` for `cannes` and `classic`.
    </ParamField>

    <ParamField path="activeWordTextColor" type="string">
      Text color of the spoken word when the highlight is drawn as a background. Not accepted by `highlight`.
    </ParamField>

    <ParamField path="textCase" type="enum<string>">
      Letter case applied to every caption word — `original`, `uppercase`, or `lowercase`.
    </ParamField>

    <ParamField path="backgroundColor" type="string">
      Caption background color. Required for `backdrop`, optional elsewhere.
    </ParamField>

    <ParamField path="backgroundEnabled" type="boolean">
      Whether the caption background is visible.
    </ParamField>

    <ParamField path="shadowColor" type="string">
      Text shadow color. Required for `cannes`, optional elsewhere.
    </ParamField>

    <ParamField path="shadowEnabled" type="boolean">
      Whether the text shadow is visible.
    </ParamField>

    <ParamField path="outlineColor" type="string">
      Text outline color. Required for `classic`, optional elsewhere.
    </ParamField>

    <ParamField path="outlineEnabled" type="boolean">
      Whether the text outline is visible.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="captionSize" type="enum<string>">
  Subtitle size (`small`, `medium`, or `large`), used if subtitles are enabled on the video
</ParamField>

<ParamField path="captionGrouping" type="enum<string>">
  Subtitle grouping (`chunked` or `singleWord`), used if subtitles are enabled on the video
</ParamField>

<ParamField path="captionPosition" type="object | null">
  Normalized subtitle `{ x, y }` coordinates from 0 to 1, or `null` for automatic placement; used if subtitles are enabled on the video

  <Expandable title="properties">
    <ParamField path="x" type="number" required>
      Horizontal position from 0 to 1
    </ParamField>

    <ParamField path="y" type="number" required>
      Vertical position from 0 to 1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="transcriptEnabled" type="boolean">
  Show transcript tab
</ParamField>

<ParamField path="commentsEnabled" type="boolean">
  Allow comments
</ParamField>

<ParamField path="downloadsEnabled" type="boolean">
  Allow downloads
</ParamField>

<ParamField path="linkScope" type="enum<string>">
  Access level — `public`, `private`, `password`, or `embedonly`
</ParamField>

<ParamField path="password" type="string">
  Password for protected videos
</ParamField>

<ParamField path="searchEngineIndexingEnabled" type="boolean">
  Allow search engine indexing
</ParamField>

<ParamField path="studioSound" type="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`.
</ParamField>

<ParamField path="microphoneVolume" type="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`.
</ParamField>

<ParamField path="systemAudioVolume" type="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`.
</ParamField>

<ParamField path="motionBlur" type="boolean">
  Blur fast zoom, pan, and cursor movement. Videos created with `create_video` start with this off — pass `true` to enable it.
</ParamField>

<ParamField path="shrinkCameraDuringZooms" type="boolean">
  Shrink camera bubbles while a zoom is active. Videos created with `create_video` start with this off — pass `true` to enable it.
</ParamField>

<ParamField path="cursor" type="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.

  <Expandable title="properties">
    <ParamField path="style" type="enum<string>">
      Cursor artwork. Use the recording OS when known. One of `mac`, `macTahoe`, `macGoldenGate`, `windows`, `touch`.
    </ParamField>

    <ParamField path="size" type="number">
      Animated cursor size multiplier from 0.5 to 6.
    </ParamField>

    <ParamField path="smoothing" type="boolean">
      Smooth cursor movement. Defaults off for new videos.
    </ParamField>

    <ParamField path="clickRipple" type="boolean">
      Show a ripple on mouse clicks. Defaults off for new videos.
    </ParamField>

    <ParamField path="hideWhenInactive" type="boolean">
      Fade the animated cursor out while inactive and back in on activity.
    </ParamField>

    <ParamField path="returnToStart" type="boolean">
      Return the cursor to its opening position at the end for cleaner loops.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="defaultClipTransition" type="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`.
</ParamField>

<ParamField path="dimensions" type="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.

  <Expandable title="properties">
    <ParamField path="width" type="number" required>
      Canvas width in pixels
    </ParamField>

    <ParamField path="height" type="number" required>
      Canvas height in pixels
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="autoRatio" type="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`.
</ParamField>

`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 a `presetId`, 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.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="presetId" type="string" required>
  Preset ID from `list_subtitle_presets`
</ParamField>

## get\_captions\_file

Get ready captions as SRT or WebVTT text. Returns `format`, `fileName`, and `content`.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="format" type="enum<string>">
  `srt` (default) or `vtt`
</ParamField>

## delete\_video

Delete a video (moves to trash).

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

## duplicate\_video

Create a copy of a video. Supports trimming to extract a time range or specific chapter.

<ParamField path="videoId" type="string" required>
  Video ID to duplicate
</ParamField>

<ParamField path="name" type="string">
  Name for the duplicate
</ParamField>

<ParamField path="startTime" type="number">
  Trim start time in seconds (use with endTime)
</ParamField>

<ParamField path="endTime" type="number">
  Trim end time in seconds (use with startTime)
</ParamField>

<ParamField path="chapterIndex" type="integer">
  Extract a specific chapter by 0-based index (cannot be combined with startTime/endTime)
</ParamField>

## export\_video

Start a video export. Use `get_export_status` to poll until the export completes or fails.

Returns an `export` object. Pass its `exportId` value to `get_export_status`.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="granularity" type="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)
</ParamField>

<ParamField path="resolution" type="enum<string>">
  `4k` for 4K; omit for default
</ParamField>

<ParamField path="fps" type="enum<string>">
  Frames per second — `30` or `60`
</ParamField>

<ParamField path="subtitles" type="boolean">
  Burn in subtitles
</ParamField>

<ParamField path="speed" type="enum<string>">
  Playback speed — `0.5`, `0.75`, `1`, `1.25`, `1.5`, `1.75`, or `2`
</ParamField>

## get\_export\_status

Get an export's current status and progress. Poll this after `export_video` until `export.status` is `completed` or `failed`; `export.downloadUrl` appears when the export is ready.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="exportId" type="string" required>
  The `export.exportId` value returned by `export_video`
</ParamField>

## add\_collaborator\_to\_video

Add a collaborator to a video. The user must be a member of your workspace.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="email" type="string" required>
  Email address of the user to add
</ParamField>

<ParamField path="role" type="enum<string>" required>
  Role to grant — `editor` or `viewer`
</ParamField>

## update\_collaborator\_on\_video

Change a collaborator's role on a video.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="userId" type="string" required>
  User ID of the collaborator
</ParamField>

<ParamField path="role" type="enum<string>" required>
  New role — `editor` or `viewer`
</ParamField>

## remove\_collaborator\_from\_video

Remove a collaborator from a video.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="userId" type="string" required>
  User ID of the collaborator to remove
</ParamField>

<Note>
  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](/docs/help/teams/how-can-i-add-a-team-member-as-an-editor-of-your-video#transfer-ownership-of-a-video) flow in the app.
</Note>


## Related topics

- [Duplicate a video](/docs/api-reference/videos/duplicate-a-video.md)
- [Video created](/docs/api-reference/videos/video-created.md)
- [Video analytics](/docs/help/sharing/analytics.md)
- [Video viewed](/docs/api-reference/videos/video-viewed.md)
- [Create a video](/docs/api-reference/videos/create-a-video.md)