Sign in
Videos

Create a video

Create a new video from an uploaded source. First create a source (POST /v1/sources), PUT the video bytes to its uploadUrl, then call this endpoint with the sourceId — it becomes the new video's first clip.

post/v1/videos

Request body

allowedEmbedDomainsstring[]

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.

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

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.

sourceIdstring required

Source ID from POST /v1/sources (kind: 'video'). Upload the video bytes to the source's uploadUrl first; the source becomes the new video's first clip.

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

Example request

{
  "allowedEmbedDomains": [
    "example.com",
    "mysite.org"
  ],
  "captionStyle": {
    "backgroundColor": "#5E51F8FF",
    "textColor": "#5E51F8FF"
  },
  "captionsDefaultEnabled": true,
  "commentsEnabled": true,
  "cursor": {
    "size": 3.05,
    "style": "macTahoe"
  },
  "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
  "defaultClipTransition": "smooth",
  "defaultPlaybackRate": 1,
  "description": "Updated description for the video",
  "dimensions": {
    "height": 1920,
    "width": 1080
  },
  "downloadsEnabled": true,
  "linkScope": "public",
  "microphoneVolume": 1.2,
  "motionBlur": true,
  "name": "Updated Video Title",
  "password": "secretpassword",
  "publishDateEnabled": true,
  "searchEngineIndexingEnabled": true,
  "shrinkCameraDuringZooms": true,
  "sourceId": "su_abc123def456",
  "studioSound": true,
  "subtitlesEnabled": true,
  "systemAudioVolume": 0.4,
  "transcriptsEnabled": true,
  "viewCountEnabled": true
}

Response

Video created

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"
      ],
      "captionGrouping": "chunked",
      "captionSize": "medium",
      "captionStyle": {
        "backgroundColor": "#5E51F8FF",
        "textColor": "#5E51F8FF"
      },
      "captionsDefaultEnabled": true,
      "commentsEnabled": true,
      "cursor": {
        "size": 3.05,
        "style": "macTahoe"
      },
      "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
      "defaultClipTransition": "smooth",
      "defaultPlaybackRate": 1,
      "downloadsEnabled": true,
      "linkScope": "org",
      "microphoneVolume": 1,
      "motionBlur": true,
      "publishDateEnabled": true,
      "searchEngineIndexingEnabled": true,
      "shrinkCameraDuringZooms": true,
      "subtitlesEnabled": true,
      "systemAudioVolume": 1,
      "transcriptsEnabled": true,
      "viewCountEnabled": true
    },
    "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 endpoint across all 1 revision of this API.