Videos

Create a video

Changed on Nov 7, 2026

Create a new video. From an uploaded source: create a source (POST /v1/sources), PUT the video bytes to its uploadUrl, then call this endpoint with the sourceId, which becomes the new video's first clip. Without a sourceId the video is empty, as the editor's New video makes; add clips with POST /v1/videos/{id}/clips (an uploaded source) or POST /v1/motion/clips (Tella Motion).

post/v1/videos

Request

Base URL
https://api.tella.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/post.ts
A function with typed inputs. Its response is checked against the schema.

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

creatorEnabledboolean

Show who created the video on the video page

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

eyeContactboolean

Eye contact correction for every camera recording in the video: AI redirects the speaker's gaze to the lens. true starts preparing each camera in the background (about as long as the recording); false restores the natural look. The response's settings.eyeContact shows the switch as asked for with status: "processing"; read the video until it is ready. Screen recordings and uploaded videos are never changed. Returns 400 when turning it on for a video with no camera recording.

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.

motionBlurAmountnumber

Motion blur strength, the editor's Motion blur slider: 0.1 (subtle) to 2 (strong), 1 is the default. Setting it turns motion blur on, so it can't be combined with motionBlur: false.

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

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. Leave it out for an empty video, as the editor's New video makes: add clips with POST /v1/videos/{id}/clips or POST /v1/motion/clips.

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.

studioSoundLevel'off' | 'low' | 'high'

Studio Sound level, as in the editor's Studio Voice panel. low and high turn Studio Sound on at that strength and regenerate the enhanced audio tracks when the level changes; off turns it off. Pass this or studioSound, or both when they agree.

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

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,
  "creatorEnabled": 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,
  "eyeContact": true,
  "keystrokes": {
    "alignment": "center",
    "animation": {
      "intro": {
        "preset": "slide_up"
      },
      "outro": {
        "preset": "fade"
      }
    },
    "colors": {
      "background": "#FFFFFF",
      "keyBackground": "#FFFFFF",
      "keyText": "#FFFFFF"
    },
    "displayDurationMs": 1000,
    "enabled": true,
    "filter": "shortcuts",
    "size": 1,
    "style": "keycap",
    "typing": "words"
  },
  "layoutAnimationStyle": "snappy",
  "linkScope": "public",
  "microphoneVolume": 1.2,
  "motionBlur": true,
  "motionBlurAmount": 1.3,
  "name": "Updated Video Title",
  "password": "secretpassword",
  "publishDateEnabled": true,
  "searchEngineIndexingEnabled": true,
  "shrinkCameraDuringZooms": true,
  "sourceId": "su_abc123def456",
  "studioSound": true,
  "studioSoundLevel": "low",
  "subtitlesEnabled": true,
  "systemAudioVolume": 0.4,
  "transcriptsEnabled": true,
  "viewCountEnabled": true,
  "zoomAnimationStyle": "brisk"
}

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"
      ],
      "callToAction": {
        "url": "https://docs.tella.com/help"
      },
      "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,
      "creatorEnabled": true,
      "cursor": {
        "size": 3.05,
        "style": "macTahoe",
        "tiltStrength": 0.5
      },
      "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
      "defaultClipTransition": "smooth",
      "defaultPlaybackRate": 1,
      "downloadsEnabled": true,
      "eyeContact": {
        "cameras": 1,
        "camerasReady": 1,
        "enabled": true,
        "status": "ready"
      },
      "keystrokes": {
        "alignment": "center",
        "animation": {
          "intro": {
            "durationMs": 500,
            "easing": {
              "bezier": [
                0.25,
                0.1,
                0.25,
                1
              ],
              "curve": "slow_down",
              "intensity": 0.5,
              "spring": {
                "damping": 12,
                "mass": 1,
                "stiffness": 200
              }
            },
            "moveY": -0.5,
            "preset": "slide_up",
            "scale": 1,
            "text": {
              "delayMs": 100,
              "order": "forward",
              "smoothing": "linear",
              "unit": "words"
            }
          },
          "motionBlur": true,
          "outro": {
            "durationMs": 500,
            "easing": {
              "bezier": [
                0.25,
                0.1,
                0.25,
                1
              ],
              "curve": "slow_down",
              "intensity": 0.5,
              "spring": {
                "damping": 12,
                "mass": 1,
                "stiffness": 200
              }
            },
            "moveY": -0.5,
            "preset": "slide_up",
            "scale": 1,
            "text": {
              "delayMs": 100,
              "order": "forward",
              "smoothing": "linear",
              "unit": "words"
            }
          },
          "textIntro": {
            "durationMs": 500,
            "easing": {
              "bezier": [
                0.25,
                0.1,
                0.25,
                1
              ],
              "curve": "slow_down",
              "intensity": 0.5,
              "spring": {
                "damping": 12,
                "mass": 1,
                "stiffness": 200
              }
            },
            "moveY": -0.5,
            "preset": "slide_up",
            "scale": 1,
            "text": {
              "delayMs": 100,
              "order": "forward",
              "smoothing": "linear",
              "unit": "words"
            }
          },
          "textOutro": {
            "durationMs": 500,
            "easing": {
              "bezier": [
                0.25,
                0.1,
                0.25,
                1
              ],
              "curve": "slow_down",
              "intensity": 0.5,
              "spring": {
                "damping": 12,
                "mass": 1,
                "stiffness": 200
              }
            },
            "moveY": -0.5,
            "preset": "slide_up",
            "scale": 1,
            "text": {
              "delayMs": 100,
              "order": "forward",
              "smoothing": "linear",
              "unit": "words"
            }
          }
        },
        "colors": {
          "background": "#FFFFFF",
          "keyBackground": "#FFFFFF",
          "keyText": "#FFFFFF"
        },
        "displayDurationMs": 1000,
        "enabled": true,
        "filter": "shortcuts",
        "size": 1,
        "style": "keycap",
        "typing": "words"
      },
      "layoutAnimationStyle": "moderate",
      "linkScope": "org",
      "microphoneVolume": 1,
      "motionBlur": true,
      "motionBlurAmount": 1,
      "publishDateEnabled": true,
      "searchEngineIndexingEnabled": true,
      "secondaryCallToAction": {
        "url": "https://docs.tella.com/help"
      },
      "shrinkCameraDuringZooms": true,
      "studioSoundLevel": "off",
      "subtitlesEnabled": true,
      "systemAudioVolume": 1,
      "thumbnailInpointMs": 12000,
      "transcriptsEnabled": true,
      "viewCountEnabled": true,
      "workspaceCallToAction": {
        "url": "https://docs.tella.com/help"
      },
      "workspaceSecondaryCallToAction": {
        "url": "https://docs.tella.com/help"
      },
      "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

Nov 7, 20260cc3fcd307ad Revision changes
- breaking
  the / request property's max was decreased to 1920.00
- breaking
  the / request property's max was decreased to 1920.00
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property /////
- info
  added the optional property ////// to the response with the status
- info
  added the optional property /////////// to the response with the status
- info
  added the required property ////// to the response with the status
Oct 30, 20260b2b8234a7db Revision changes
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status

Operation history (15 revisions)