Skip to main content
POST
Create a video

Authorizations

​
Authorization
string
header
required

API key obtained from your Tella account settings

Body

application/json

Request body for creating a video from an uploaded source.

​
sourceId
string
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.

Minimum string length: 1
Example:

"su_abc123def456"

​
allowedEmbedDomains
string[]

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

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

Example:

true

​
captionFontFamily
string

Subtitle font family. On write, one of Tella's catalog font families (the list the editor's font picker offers, and the same one fontFamily accepts on text overlays), or the video's current family to keep an uploaded font. Reads report the family the subtitles render with, which on videos styled before the catalog can be a legacy bundled family such as Arial.

Minimum string length: 1
Example:

"Inter"

​
captionFontSize
number

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.

Required range: 40 <= x <= 200
Example:

64

​
captionFontWeight
number

Variable-font weight axis — 100 (thin) to 1000. Clamped to the range the family supports, so a read reports the weight that renders. Sent without captionFontFamily, it re-weights the video's current font.

Required range: 100 <= x <= 1000
Example:

500

​
captionGrouping
enum<string>

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

Available options:
chunked,
singleWord
​
captionLinesPerBlock
integer

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.

Required range: 0 <= x <= 3
Example:

1

​
captionPosition
object | null

Normalized subtitle position; null restores automatic placement. Applies if subtitles are enabled on the video.

​
captionSize
enum<string>

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

Available options:
small,
medium,
large
​
captionStyle
Backdrop · object

Subtitle style. Applies if subtitles are enabled on the video. Background, shadow, and outline colors and toggles are available on every style.

​
captionsDefaultEnabled
boolean

Show subtitles to viewers by default

Example:

true

​
commentEmailsEnabled
boolean

Send email notifications for new comments

Example:

false

​
commentsEnabled
boolean

Allow viewers to comment

Example:

true

​
cursor
object

Animated cursor settings to update. Omitted nested fields keep their current values.

​
customThumbnailURL
string<uri>

Custom thumbnail image URL

Example:

"https://example.com/custom-thumbnail.jpg"

​
defaultClipTransition
enum<string>

How each clip enters from the previous one. A clip can override it with its own transition; see PATCH /v1/videos/{id}/clips/{clipId}.

Available options:
smooth,
hard_cut
Example:

"hard_cut"

​
defaultPlaybackRate
number

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

Required range: 0.5 <= x <= 2
Example:

1

​
description
string

Video description

Maximum string length: 5000
Example:

"Updated description for the video"

​
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).

Example:
​
downloadsEnabled
boolean

Allow viewers to download the video

Example:

true

​
layoutAnimationStyle
enum<string>

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.

Available options:
gentlest,
gentle,
relaxed,
moderate,
brisk,
snappy,
snappiest
Example:

"snappy"

​
linkScope
enum<string>

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

Available options:
public,
private,
password,
embedonly
Example:

"public"

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

Required range: 0 <= x <= 2
Example:

1.2

​
motionBlur
boolean

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

Example:

true

​
name
string

Video title

Required string length: 1 - 255
Example:

"Updated Video Title"

​
password
string

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

Required string length: 1 - 255
Example:

"secretpassword"

​
publishDateEnabled
boolean

Show publish date on video page

Example:

true

​
rawDownloadsEnabled
boolean

Allow viewers to download raw source files

Example:

false

​
searchEngineIndexingEnabled
boolean

Allow search engines to index the video page

Example:

true

​
shrinkCameraDuringZooms
boolean

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

Example:

true

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

Example:

true

​
subtitlesEnabled
boolean

Allow viewers to enable subtitles

Example:

true

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

Required range: 0 <= x <= 2
Example:

0.4

​
transcriptsEnabled
boolean

Show transcript panel to viewers

Example:

true

​
viewCountEnabled
boolean

Show view count on video page

Example:

true

​
zoomAnimationStyle
enum<string>

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

Available options:
gentlest,
gentle,
relaxed,
moderate,
brisk,
snappy,
snappiest
Example:

"brisk"

Response

Video created

​
video
object
required

Detailed information about a video including chapters, transcript, and exports

Last modified on October 6, 2026