Videos

Update a video

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

patch/v1/videos/{id}

Request

  • Base URL: https://api.tella.com
  • URL: https://api.tella.com/v1/videos/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Unique video identifier

Example:vid_abc123def456

Request body

allowedEmbedDomainsstring[]

Restrict embedding to these domains only (Premium feature). Empty array allows all domains.

autoRatioboolean

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 the canvas changes ratio class, layouts are remapped like a dimensions change. false pins the current size. Pass either autoRatio or dimensions, not both.

captionFontFamilystring

Subtitle font family. On write, one of Tella's catalog font families or the built-in subtitle families Dela Gothic One, Lato, Georgia, and Arial, or the video's current family to keep an uploaded font. Reads report the family the subtitles render with.

captionFontSizenumber

Exact subtitle text size, 40 to 200 — the editor's Size slider. captionSize is the same setting in buckets (small 40, medium 64, large 80), so a request passes one or the other, not both.

captionFontWeightnumber

Subtitle font weight, 100 (thin) to 1000. Catalog fonts clamp to their supported range; built-in subtitle fonts outside the catalog snap to an available weight. Dela Gothic One uses 400 only; Arial uses 400 or 700. Reads report the weight that renders. Sent without captionFontFamily, it re-weights the video's current font.

captionGrouping'chunked' | 'singleWord'

How subtitle text is grouped: sentence chunks or one word at a time.

captionLinesPerBlockinteger

Lines a caption block may span when captionGrouping is chunked: 1, 2, or 3, or 0 for no limit, where blocks only break on pauses and sentence ends.

captionSize'small' | 'medium' | 'large'

Subtitle text size. Applies if subtitles are enabled on the video.

captionsDefaultEnabledboolean

Show subtitles to viewers by default

commentEmailsEnabledboolean

Send email notifications for new comments

commentsEnabledboolean

Allow viewers to comment

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

defaultPlaybackRatenumber

Default playback speed (0.5-2.0). Viewers can still adjust.

descriptionstring

Video description

downloadsEnabledboolean

Allow viewers to download the video

layoutAnimationStyle'gentlest' | 'gentle' | 'relaxed' | 'moderate' | 'brisk' | 'snappy' | 'snappiest'

How layout transitions animate, gentlest to snappiest. Changing it leaves zooms as they were: when zooms have no zoomAnimationStyle of their own, they keep the previous style.

linkScope'public' | 'private' | 'password' | 'embedonly'

Access level: public (anyone with link), private (org members only), password (requires password), embedonly (only viewable when embedded)

microphoneVolumenumber

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

motionBlurboolean

Blur fast zoom, pan, and cursor movement. Defaults on for new videos.

namestring

Video title

passwordstring

Password for viewing. Required when linkScope is 'password', ignored otherwise.

publishDateEnabledboolean

Show publish date on video page

rawDownloadsEnabledboolean

Allow viewers to download raw source files

searchEngineIndexingEnabledboolean

Allow search engines to index the video page

shrinkCameraDuringZoomsboolean

Shrink camera bubbles while a zoom is active. Defaults on.

studioSoundboolean

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.

subtitlesEnabledboolean

Allow viewers to enable subtitles

systemAudioVolumenumber

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

transcriptsEnabledboolean

Show transcript panel to viewers

viewCountEnabledboolean

Show view count on video page

zoomAnimationStyle'gentlest' | 'gentle' | 'relaxed' | 'moderate' | 'brisk' | 'snappy' | 'snappiest'

How zooms ease in, out, and between each other, gentlest to snappiest. Independent of layoutAnimationStyle.

Example request

{
  "allowedEmbedDomains": [
    "example.com",
    "mysite.org"
  ],
  "autoRatio": true,
  "captionFontFamily": "Inter",
  "captionFontSize": 64,
  "captionFontWeight": 500,
  "captionLinesPerBlock": 1,
  "captionStyle": {
    "activeWordTextColor": "#5E51F8FF",
    "backgroundColor": "#5E51F8FF",
    "highlightColor": "#5E51F8FF",
    "outlineColor": "#5E51F8FF",
    "shadowColor": "#5E51F8FF",
    "textColor": "#5E51F8FF"
  },
  "captionsDefaultEnabled": true,
  "commentsEnabled": true,
  "cursor": {
    "size": 3.05,
    "style": "macTahoe",
    "tiltStrength": 0.5
  },
  "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
  "defaultClipTransition": "smooth",
  "defaultPlaybackRate": 1,
  "description": "Updated description for the video",
  "dimensions": {
    "height": 1920,
    "width": 1080
  },
  "downloadsEnabled": true,
  "layoutAnimationStyle": "snappy",
  "linkScope": "public",
  "microphoneVolume": 1.2,
  "motionBlur": true,
  "name": "Updated Video Title",
  "password": "secretpassword",
  "publishDateEnabled": true,
  "searchEngineIndexingEnabled": true,
  "shrinkCameraDuringZooms": true,
  "studioSound": true,
  "subtitlesEnabled": true,
  "systemAudioVolume": 0.4,
  "transcriptsEnabled": true,
  "viewCountEnabled": true,
  "zoomAnimationStyle": "brisk"
}

Response

OK

Example response

{
  "video": {
    "aspectRatio": "16:9",
    "backgroundMusic": {
      "durationMs": 180036,
      "name": "Calm Product Tour",
      "url": "https://ucarecdn.com/example-track/",
      "volume": 0.2
    },
    "chapters": [
      {
        "description": "Overview of what we'll cover",
        "title": "Introduction"
      }
    ],
    "clipIds": [
      "cl_abc123",
      "cl_def456"
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "description": "Learn how to create and share your first video",
    "dimensions": {
      "height": 1080,
      "width": 1920
    },
    "durationSeconds": 125.5,
    "exports": [
      {
        "downloadUrl": "https://cdn.tella.tv/exports/vid_abc123/video.mp4",
        "exportId": "Export-Story-vid_abc123def456/2026-01-15T10:00:00Z/Story/1920x1080/30FPS",
        "progress": 100,
        "status": "completed",
        "updatedAt": "2024-01-15T15:00:00.000Z"
      }
    ],
    "id": "vid_abc123def456",
    "links": {
      "embedPage": "https://www.tella.tv/video/vid_abc123def456/embed",
      "viewPage": "https://www.tella.tv/video/vid_abc123def456/view"
    },
    "name": "Getting Started with Tella",
    "playlistIds": [
      "pl_abc123",
      "pl_def456"
    ],
    "settings": {
      "allowedEmbedDomains": [
        "example.com",
        "mysite.org"
      ],
      "captionFontFamily": "Inter",
      "captionFontSize": 64,
      "captionFontWeight": 500,
      "captionGrouping": "chunked",
      "captionLinesPerBlock": 1,
      "captionSize": "medium",
      "captionStyle": {
        "activeWordTextColor": "#5E51F8FF",
        "backgroundColor": "#5E51F8FF",
        "highlightColor": "#5E51F8FF",
        "outlineColor": "#5E51F8FF",
        "shadowColor": "#5E51F8FF",
        "textColor": "#5E51F8FF"
      },
      "captionsDefaultEnabled": true,
      "commentsEnabled": true,
      "cursor": {
        "size": 3.05,
        "style": "macTahoe",
        "tiltStrength": 0.5
      },
      "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
      "defaultClipTransition": "smooth",
      "defaultPlaybackRate": 1,
      "downloadsEnabled": true,
      "layoutAnimationStyle": "moderate",
      "linkScope": "org",
      "microphoneVolume": 1,
      "motionBlur": true,
      "publishDateEnabled": true,
      "searchEngineIndexingEnabled": true,
      "shrinkCameraDuringZooms": true,
      "subtitlesEnabled": true,
      "systemAudioVolume": 1,
      "thumbnailInpointMs": 12000,
      "transcriptsEnabled": true,
      "viewCountEnabled": true,
      "zoomAnimationStyle": "moderate"
    },
    "thumbnails": {
      "large": {
        "gif": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.gif",
        "jpg": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.jpg",
        "mp4": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.mp4",
        "webp": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.webp"
      },
      "medium": {
        "gif": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.gif",
        "jpg": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.jpg",
        "mp4": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.mp4",
        "webp": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.webp"
      },
      "small": {
        "gif": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.gif",
        "jpg": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.jpg",
        "mp4": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.mp4",
        "webp": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.webp"
      },
      "xl": {
        "gif": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.gif",
        "jpg": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.jpg",
        "mp4": "https://cdn.tella.tv/thumbnails/vid_abc123/640x360.mp4",
        "webp": "https://cdn.tella.tv/thumbnails/vid_abc123/1920x1080.webp"
      }
    },
    "transcript": {
      "language": "en",
      "sentences": [
        {
          "endSeconds": 2.3,
          "startSeconds": 0.5,
          "text": "Hello and welcome to this tutorial."
        }
      ],
      "status": "ready",
      "text": "Hello and welcome to this tutorial..."
    },
    "updatedAt": "2024-01-15T14:45:00.000Z",
    "views": 1234
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.