---
title: "Update a video"
method: PATCH
path: "/v1/videos/{id}"
tags: ["Videos"]
---

# Update a video

`PATCH /v1/videos/{id}`

Update a video's settings including viewer options, download permissions, access controls, and metadata. Some features require Premium plan.

## Path parameters

- `id` string, required — Unique video identifier

## Request body

- UpdateVideoRequest — Request body for updating a video. At least one field must be provided.
  - `allowedEmbedDomains` string[] — Restrict embedding to these domains only (Premium feature). Empty array allows all domains.
  - `captionGrouping` 'chunked' | 'singleWord' — How subtitle text is grouped: sentence chunks or one word at a time.
  - `captionPosition` CaptionPosition — Normalized subtitle position. Applies if subtitles are enabled on the video. Null uses automatic placement.
    - `x` number, required
    - `y` number, required
  - `captionSize` 'small' | 'medium' | 'large' — Subtitle text size. Applies if subtitles are enabled on the video.
  - `captionStyle` union — Subtitle style. Applies if subtitles are enabled on the video. Every style-specific field is required and fields from other styles are rejected.
    - object
      - `backgroundColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `name` 'backdrop', required
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `wordLevelHighlights` boolean, required
    - object
      - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `name` 'highlight', required
      - `primaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `secondaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
    - object
      - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `name` 'mono', required
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
    - object
      - `name` 'cannes', required
      - `shadowColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
    - object
      - `name` 'classic', required
      - `outlineColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
  - `captionsDefaultEnabled` boolean — Show subtitles to viewers by default
  - `commentEmailsEnabled` boolean — Send email notifications for new comments
  - `commentsEnabled` boolean — Allow viewers to comment
  - `cursor` CursorSettingsUpdate — Animated cursor settings to update. Omitted nested fields keep their current values.
    - `clickRipple` boolean — Show a ripple on mouse clicks. Defaults off for new videos.
    - `hideWhenInactive` boolean — Fade the animated cursor out while inactive and back in when activity resumes.
    - `returnToStart` boolean — Move the cursor back to its opening position at the end for cleaner loops.
    - `size` number — Animated cursor size multiplier.
    - `smoothing` boolean — Smooth cursor movement. Defaults off for new videos.
    - `style` 'mac' | 'macTahoe' | 'macGoldenGate' | 'windows' | 'touch' — Animated cursor artwork. mac is the pre-Tahoe style; macTahoe and macGoldenGate match those macOS generations; windows and touch use platform-specific artwork.
  - `customThumbnailURL` string, uri — Custom thumbnail image URL
  - `defaultClipTransition` 'smooth' | 'hard_cut' — How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
  - `defaultPlaybackRate` number — Default playback speed (0.5-2.0). Viewers can still adjust.
  - `description` string — Video description
  - `dimensions` object — Canvas size in pixels. Changing it also remaps every clip and section layout to a ratio-appropriate equivalent (clips using a custom layout fall back to a standard one), exactly like switching size in the editor's Setup → Size. No-op when the video already has the requested size. The editor's presets: 1920x1080 (16:9), 1920x1200 (16:10), 1440x1080 (4:3), 1080x1080 (1:1), 1080x1350 (4:5), 1080x1920 (9:16).
    - `height` number, required — Canvas height in pixels
    - `width` number, required — Canvas width in pixels
  - `downloadsEnabled` boolean — Allow viewers to download the video
  - `linkScope` 'public' | 'private' | 'password' | 'embedonly' — Access level: public (anyone with link), private (org members only), password (requires password), embedonly (only viewable when embedded)
  - `microphoneVolume` 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 or clear those with `PATCH /v1/videos/{id}/clips/{clipId}`.
  - `motionBlur` boolean — Blur fast zoom, pan, and cursor movement. Defaults on for new videos.
  - `name` string — Video title
  - `password` string — Password for viewing. Required when linkScope is 'password', ignored otherwise.
  - `publishDateEnabled` boolean — Show publish date on video page
  - `rawDownloadsEnabled` boolean — Allow viewers to download raw source files
  - `searchEngineIndexingEnabled` boolean — Allow search engines to index the video page
  - `shrinkCameraDuringZooms` boolean — Shrink camera bubbles while a zoom is active. Defaults on.
  - `studioSound` boolean — Studio Sound (AI audio enhancement) master switch. Enabling it also starts generating the enhanced audio tracks in the background; playback and exports use them once ready and fall back to the raw audio until then.
  - `subtitlesEnabled` boolean — Allow viewers to enable subtitles
  - `systemAudioVolume` number — Volume of the system/screen audio across the whole video — everything that is not microphone audio. 1 is the recorded level, 0 mutes it, 2 doubles it. Clips that set their own `systemAudioVolume` keep it — change or clear those with `PATCH /v1/videos/{id}/clips/{clipId}`.
  - `transcriptsEnabled` boolean — Show transcript panel to viewers
  - `viewCountEnabled` boolean — Show view count on video page

## Response `200`

OK

- object
  - `video` VideoDetail, required — Detailed information about a video including chapters, transcript, and exports
    - `aspectRatio` string, required — Video aspect ratio (e.g., '16:9', '9:16')
    - `backgroundMusic` BackgroundMusic, required — One video-wide track that loops over the whole video and is included in exports
      - `durationMs` number, required — Audio track duration in milliseconds
      - `name` string, nullable, required — Optional display name for the track
      - `url` string, uri, required — HTTPS URL of the audio track
      - `volume` number, required — Track volume from 0 (silent) to 1 (full volume)
    - `chapters` Chapter[], required — Video chapters/sections
      - `description` string, required — Chapter description
      - `timestampSeconds` number, required — Chapter start time in seconds
      - `title` string, required — Chapter title
    - `clipIds` string[], required — Ordered IDs of the clips in the video. Use `/v1/videos/{id}/clips/{clipId}` to fetch each one.
    - `createdAt` string, date-time, required — ISO 8601 datetime
    - `description` string, required — Video description
    - `dimensions` object, required — Canvas size in pixels
      - `height` number, required
      - `width` number, required
    - `durationSeconds` number, required — Video duration in seconds
    - `exports` ExportStatus[], required — Available exports and their status
      - `downloadUrl` string, uri, nullable, required — Download URL when export is completed, null otherwise
      - `exportId` string, required — Unique identifier for the export job
      - `progress` number, nullable, required — Export progress percentage (0-100), null if not started
      - `status` 'queued' | 'running' | 'completed' | 'failed', required — Current export status
      - `updatedAt` string, date-time, required — ISO 8601 datetime of last status update
    - `id` string, required — Unique video identifier
    - `links` VideoLinks, required — URLs related to a video
      - `embedPage` string, uri, required — URL for embedding the video
      - `viewPage` string, uri, required — URL to view the video on Tella
    - `name` string, required — Video title
    - `playlistIds` string[], required — IDs of playlists containing this video
    - `settings` VideoSettings, required — Video playback and access settings
      - `allowedEmbedDomains` string[], required — Restrict embedding to these domains only (Premium feature). Empty array allows all domains.
      - `captionGrouping` 'chunked' | 'singleWord', required — How subtitle text is grouped: sentence chunks or one word at a time.
      - `captionPosition` CaptionPosition, required — Normalized subtitle position. Applies if subtitles are enabled on the video. Null uses automatic placement.
        - `x` number, required
        - `y` number, required
      - `captionSize` 'small' | 'medium' | 'large', required — Subtitle text size. Applies if subtitles are enabled on the video.
      - `captionStyle` union, required — Subtitle style. Applies if subtitles are enabled on the video. Every style-specific field is required and fields from other styles are rejected.
        - object
          - `backgroundColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `name` 'backdrop', required
          - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `wordLevelHighlights` boolean, required
        - object
          - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `name` 'highlight', required
          - `primaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `secondaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - object
          - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `name` 'mono', required
          - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - object
          - `name` 'cannes', required
          - `shadowColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - object
          - `name` 'classic', required
          - `outlineColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
          - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `captionsDefaultEnabled` boolean, required — Show subtitles to viewers by default
      - `commentEmailsEnabled` boolean, required — Send email notifications for new comments
      - `commentsEnabled` boolean, required — Allow viewers to comment
      - `cursor` CursorSettings, required — Animated cursor settings
        - `clickRipple` boolean, required — Show a ripple on mouse clicks. Defaults off for new videos.
        - `hideWhenInactive` boolean, required — Fade the animated cursor out while inactive and back in when activity resumes.
        - `returnToStart` boolean, required — Move the cursor back to its opening position at the end for cleaner loops.
        - `size` number, required — Animated cursor size multiplier.
        - `smoothing` boolean, required — Smooth cursor movement. Defaults off for new videos.
        - `style` 'mac' | 'macTahoe' | 'macGoldenGate' | 'windows' | 'touch', required — Animated cursor artwork. mac is the pre-Tahoe style; macTahoe and macGoldenGate match those macOS generations; windows and touch use platform-specific artwork.
      - `customThumbnailURL` string, uri, nullable, required — Custom thumbnail image URL
      - `defaultClipTransition` 'smooth' | 'hard_cut', required — How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
      - `defaultPlaybackRate` number, required — Default playback speed (0.5-2.0). Viewers can still adjust.
      - `downloadsEnabled` boolean, required — Allow viewers to download the video
      - `linkScope` 'public' | 'private' | 'org' | 'password' | 'embedonly', required — Current video access level. The read-only `org` value means the video is visible across its workspace; public updates intentionally do not accept that value.
      - `microphoneVolume` number, required — Volume of the microphone (webcam) audio across the video. 1 is the recorded level, 0 mutes it, 2 doubles it. A clip can override it for one of its sources.
      - `motionBlur` boolean, required — Blur fast zoom, pan, and cursor movement. Defaults on for new videos.
      - `publishDateEnabled` boolean, required — Show publish date on video page
      - `rawDownloadsEnabled` boolean, required — Allow viewers to download raw source files
      - `searchEngineIndexingEnabled` boolean, required — Allow search engines to index the video page
      - `shrinkCameraDuringZooms` boolean, required — Shrink camera bubbles while a zoom is active. Defaults on.
      - `studioSound` boolean, required — Studio Sound (AI audio enhancement) master switch for the video. Individual clips can opt out via the clip's `studioSound` field.
      - `subtitlesEnabled` boolean, required — Allow viewers to enable subtitles
      - `systemAudioVolume` number, required — Volume of the system/screen audio across the video — everything that is not microphone audio. 1 is the recorded level, 0 mutes it, 2 doubles it. A clip can override it for one of its sources.
      - `transcriptsEnabled` boolean, required — Show transcript panel to viewers
      - `viewCountEnabled` boolean, required — Show view count on video page
    - `thumbnails` Thumbnails, required — Video thumbnails organized by size, with format options for each
      - `large` ThumbnailFormats — Thumbnail URLs in various formats for a specific size
        - `gif` string, uri — Animated GIF thumbnail URL (medium and small sizes only)
        - `jpg` string, uri — JPEG thumbnail URL
        - `mp4` string, uri — Animated MP4 thumbnail URL (medium and small sizes only)
        - `webp` string, uri — WebP thumbnail URL
      - `medium` ThumbnailFormats — Thumbnail URLs in various formats for a specific size
        - `gif` string, uri — Animated GIF thumbnail URL (medium and small sizes only)
        - `jpg` string, uri — JPEG thumbnail URL
        - `mp4` string, uri — Animated MP4 thumbnail URL (medium and small sizes only)
        - `webp` string, uri — WebP thumbnail URL
      - `small` ThumbnailFormats — Thumbnail URLs in various formats for a specific size
        - `gif` string, uri — Animated GIF thumbnail URL (medium and small sizes only)
        - `jpg` string, uri — JPEG thumbnail URL
        - `mp4` string, uri — Animated MP4 thumbnail URL (medium and small sizes only)
        - `webp` string, uri — WebP thumbnail URL
      - `xl` ThumbnailFormats — Thumbnail URLs in various formats for a specific size
        - `gif` string, uri — Animated GIF thumbnail URL (medium and small sizes only)
        - `jpg` string, uri — JPEG thumbnail URL
        - `mp4` string, uri — Animated MP4 thumbnail URL (medium and small sizes only)
        - `webp` string, uri — WebP thumbnail URL
    - `transcript` Transcript, required — Video transcript data
      - `language` string, nullable, required — Detected language code (e.g., 'en', 'es')
      - `sentences` Sentence[], nullable, required — Sentences with timestamps
        - `endSeconds` number, required — Sentence end time in seconds
        - `startSeconds` number, required — Sentence start time in seconds
        - `text` string, required — Sentence text
      - `status` 'ready' | 'processing' | 'failed', required — Transcript generation status
      - `text` string, nullable, required — Full transcript text
    - `updatedAt` string, date-time, required — ISO 8601 datetime
    - `views` integer, required — Total view count

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/ba2bb13928a5/schema)