curl --request GET \
--url https://api.tella.com/v1/videos/{id}/timeline \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/timeline"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tella.com/v1/videos/{id}/timeline', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/timeline",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/timeline"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tella.com/v1/videos/{id}/timeline")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/timeline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"clips": [
{
"contents": {
"blurs": 4503599627370495,
"cuts": 4503599627370495,
"highlights": 4503599627370495,
"layouts": 4503599627370495,
"overlays": 4503599627370495,
"soundEffects": 4503599627370495,
"textOverlays": 4503599627370495,
"transcriptWords": 4503599627370495,
"zooms": 4503599627370495
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"order": 0,
"timelineStartMs": 1
}
],
"included": [
"settings"
],
"video": {
"aspectRatio": "16:9",
"description": "<string>",
"dimensions": {
"height": 123,
"width": 123
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"updatedAt": "<string>"
},
"details": {
"clips": [
{
"clipId": "<string>",
"background": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"blurs": [
{
"dimensions": {
"heightPct": 50,
"widthPct": 50
},
"durationMs": 2000,
"id": "ly_abc123",
"intensity": 0.7,
"point": {
"xPct": 25,
"yPct": 25
},
"startTimeMs": 1000,
"type": "blur"
}
],
"cuts": [
{
"durationMs": 750,
"startTimeMs": 1500
}
],
"highlights": [
{
"dimensions": {
"heightPct": 50,
"widthPct": 50
},
"durationMs": 2000,
"id": "ly_abc123",
"intensity": 0.7,
"point": {
"xPct": 25,
"yPct": 25
},
"startTimeMs": 1000,
"type": "blur"
}
],
"layoutSceneType": "combi",
"layouts": [
{
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"crop": {
"bottom": 1,
"left": 1,
"right": 1,
"top": 1
},
"durationMs": 5000,
"followsBase": true,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"popOut": {
"amount": 0.25,
"background": "original",
"color": "<string>",
"outlineColor": "<string>",
"outlineWidth": 0.025
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
],
"microphoneVolume": 1,
"overlays": [
{
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"id": "ly_abc123",
"point": {
"xPct": 30,
"yPct": 30
},
"startTimeMs": 1000,
"transition": "hard_cut",
"type": "image",
"zIndex": 0,
"imageUrl": "<string>",
"name": "Logo",
"sourceId": "su_abc123"
}
],
"soundEffects": [
{
"durationMs": 3000,
"id": "ly_abc123",
"startTimeMs": 1000,
"volume": 1,
"name": "Whoosh",
"sourceId": "su_abc123"
}
],
"studioSound": true,
"systemAudioVolume": 1,
"textOverlays": [
{
"background": {
"color": "#5E51F8FF",
"type": "solid"
},
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"fontFamily": "Inter",
"fontSize": 81,
"fontWeight": 500,
"fontWidth": 100,
"id": "ly_abc123",
"outline": "#000000FF",
"point": {
"xPct": 30,
"yPct": 30
},
"shadow": "subtle",
"startTimeMs": 1000,
"text": "Welcome back",
"textAlign": "center",
"transition": "hard_cut",
"zIndex": 0
}
],
"transcript": {
"text": "<string>",
"wordCount": 4503599627370495
},
"words": [
{
"breakAfter": false,
"endTimeMs": 1800,
"hidden": false,
"index": 12,
"keepWithNext": false,
"startTimeMs": 1500,
"text": "Hello"
}
],
"zooms": [
{
"durationMs": 2000,
"id": "ef_abc123",
"startTimeMs": 1000,
"type": "manualZoom",
"focusPoint": {
"xPct": 50,
"yPct": 50
},
"scale": 2
}
]
}
],
"video": {
"backgroundMusic": {
"durationMs": 180036,
"name": "Calm Product Tour",
"url": "https://ucarecdn.com/example-track/",
"volume": 0.2
},
"chapters": [
{
"description": "Overview of what we'll cover",
"timestampSeconds": 0,
"title": "Introduction"
}
],
"settings": {
"allowedEmbedDomains": [
"example.com",
"mysite.org"
],
"captionFontFamily": "Inter",
"captionFontSize": 64,
"captionFontWeight": 500,
"captionGrouping": "chunked",
"captionLinesPerBlock": 1,
"captionPosition": {
"x": 0.5,
"y": 0.5
},
"captionSize": "medium",
"captionStyle": {
"backgroundColor": "#5E51F8FF",
"name": "backdrop",
"textColor": "#5E51F8FF",
"wordLevelHighlights": true,
"activeWordTextColor": "#5E51F8FF",
"backgroundEnabled": true,
"highlightColor": "#5E51F8FF",
"highlightMode": "text",
"outlineColor": "#5E51F8FF",
"outlineEnabled": true,
"shadowColor": "#5E51F8FF",
"shadowEnabled": true,
"textCase": "original"
},
"captionsDefaultEnabled": true,
"commentEmailsEnabled": false,
"commentsEnabled": true,
"cursor": {
"clickRipple": false,
"hideWhenInactive": false,
"returnToStart": false,
"size": 3.05,
"smoothing": false,
"style": "macTahoe"
},
"customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
"defaultClipTransition": "hard_cut",
"defaultPlaybackRate": 1,
"downloadsEnabled": true,
"layoutAnimationStyle": "moderate",
"linkScope": "org",
"microphoneVolume": 1,
"motionBlur": true,
"publishDateEnabled": true,
"rawDownloadsEnabled": false,
"searchEngineIndexingEnabled": true,
"shrinkCameraDuringZooms": true,
"studioSound": false,
"subtitlesEnabled": true,
"systemAudioVolume": 1,
"thumbnailInpointMs": 12000,
"transcriptsEnabled": true,
"viewCountEnabled": true,
"zoomAnimationStyle": "moderate"
}
}
}
}{
"docsUrl": "https://docs.tella.com/",
"error": "bad_request",
"message": "The request was malformed or contained invalid parameters."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unauthorized",
"message": "Authentication is required. Provide a valid API key."
}{
"docsUrl": "https://docs.tella.com/",
"error": "forbidden",
"message": "You don't have permission to access this resource."
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_found",
"message": "The requested resource was not found."
}{
"docsUrl": "https://docs.tella.com/",
"error": "conflict",
"message": "The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles."
}{
"docsUrl": "https://docs.tella.com/",
"error": "rate_limited",
"message": "You have exceeded the rate limit. Please slow down."
}{
"docsUrl": "https://docs.tella.com/",
"error": "server_error",
"message": "An unexpected error occurred"
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_implemented",
"message": "The requested operation is not implemented."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unavailable",
"message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}Get a video's timeline
Returns a compact ordered timeline outline by default: video identity, version, dimensions and duration plus every clip’s video-timeline start, playback duration and content counts. Use include to fetch specific video or clip details, optionally scoped by clipIds; the complete outline remains in every response. Use include=all for the complete edit state. Effect and word times are ms on each clip’s playback timeline (cuts applied). Raw cuts retain the source-recording timing used by the clip endpoints.
curl --request GET \
--url https://api.tella.com/v1/videos/{id}/timeline \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/timeline"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tella.com/v1/videos/{id}/timeline', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/timeline",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/timeline"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tella.com/v1/videos/{id}/timeline")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/timeline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"clips": [
{
"contents": {
"blurs": 4503599627370495,
"cuts": 4503599627370495,
"highlights": 4503599627370495,
"layouts": 4503599627370495,
"overlays": 4503599627370495,
"soundEffects": 4503599627370495,
"textOverlays": 4503599627370495,
"transcriptWords": 4503599627370495,
"zooms": 4503599627370495
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"order": 0,
"timelineStartMs": 1
}
],
"included": [
"settings"
],
"video": {
"aspectRatio": "16:9",
"description": "<string>",
"dimensions": {
"height": 123,
"width": 123
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"updatedAt": "<string>"
},
"details": {
"clips": [
{
"clipId": "<string>",
"background": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"blurs": [
{
"dimensions": {
"heightPct": 50,
"widthPct": 50
},
"durationMs": 2000,
"id": "ly_abc123",
"intensity": 0.7,
"point": {
"xPct": 25,
"yPct": 25
},
"startTimeMs": 1000,
"type": "blur"
}
],
"cuts": [
{
"durationMs": 750,
"startTimeMs": 1500
}
],
"highlights": [
{
"dimensions": {
"heightPct": 50,
"widthPct": 50
},
"durationMs": 2000,
"id": "ly_abc123",
"intensity": 0.7,
"point": {
"xPct": 25,
"yPct": 25
},
"startTimeMs": 1000,
"type": "blur"
}
],
"layoutSceneType": "combi",
"layouts": [
{
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"crop": {
"bottom": 1,
"left": 1,
"right": 1,
"top": 1
},
"durationMs": 5000,
"followsBase": true,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"popOut": {
"amount": 0.25,
"background": "original",
"color": "<string>",
"outlineColor": "<string>",
"outlineWidth": 0.025
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
],
"microphoneVolume": 1,
"overlays": [
{
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"id": "ly_abc123",
"point": {
"xPct": 30,
"yPct": 30
},
"startTimeMs": 1000,
"transition": "hard_cut",
"type": "image",
"zIndex": 0,
"imageUrl": "<string>",
"name": "Logo",
"sourceId": "su_abc123"
}
],
"soundEffects": [
{
"durationMs": 3000,
"id": "ly_abc123",
"startTimeMs": 1000,
"volume": 1,
"name": "Whoosh",
"sourceId": "su_abc123"
}
],
"studioSound": true,
"systemAudioVolume": 1,
"textOverlays": [
{
"background": {
"color": "#5E51F8FF",
"type": "solid"
},
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"fontFamily": "Inter",
"fontSize": 81,
"fontWeight": 500,
"fontWidth": 100,
"id": "ly_abc123",
"outline": "#000000FF",
"point": {
"xPct": 30,
"yPct": 30
},
"shadow": "subtle",
"startTimeMs": 1000,
"text": "Welcome back",
"textAlign": "center",
"transition": "hard_cut",
"zIndex": 0
}
],
"transcript": {
"text": "<string>",
"wordCount": 4503599627370495
},
"words": [
{
"breakAfter": false,
"endTimeMs": 1800,
"hidden": false,
"index": 12,
"keepWithNext": false,
"startTimeMs": 1500,
"text": "Hello"
}
],
"zooms": [
{
"durationMs": 2000,
"id": "ef_abc123",
"startTimeMs": 1000,
"type": "manualZoom",
"focusPoint": {
"xPct": 50,
"yPct": 50
},
"scale": 2
}
]
}
],
"video": {
"backgroundMusic": {
"durationMs": 180036,
"name": "Calm Product Tour",
"url": "https://ucarecdn.com/example-track/",
"volume": 0.2
},
"chapters": [
{
"description": "Overview of what we'll cover",
"timestampSeconds": 0,
"title": "Introduction"
}
],
"settings": {
"allowedEmbedDomains": [
"example.com",
"mysite.org"
],
"captionFontFamily": "Inter",
"captionFontSize": 64,
"captionFontWeight": 500,
"captionGrouping": "chunked",
"captionLinesPerBlock": 1,
"captionPosition": {
"x": 0.5,
"y": 0.5
},
"captionSize": "medium",
"captionStyle": {
"backgroundColor": "#5E51F8FF",
"name": "backdrop",
"textColor": "#5E51F8FF",
"wordLevelHighlights": true,
"activeWordTextColor": "#5E51F8FF",
"backgroundEnabled": true,
"highlightColor": "#5E51F8FF",
"highlightMode": "text",
"outlineColor": "#5E51F8FF",
"outlineEnabled": true,
"shadowColor": "#5E51F8FF",
"shadowEnabled": true,
"textCase": "original"
},
"captionsDefaultEnabled": true,
"commentEmailsEnabled": false,
"commentsEnabled": true,
"cursor": {
"clickRipple": false,
"hideWhenInactive": false,
"returnToStart": false,
"size": 3.05,
"smoothing": false,
"style": "macTahoe"
},
"customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
"defaultClipTransition": "hard_cut",
"defaultPlaybackRate": 1,
"downloadsEnabled": true,
"layoutAnimationStyle": "moderate",
"linkScope": "org",
"microphoneVolume": 1,
"motionBlur": true,
"publishDateEnabled": true,
"rawDownloadsEnabled": false,
"searchEngineIndexingEnabled": true,
"shrinkCameraDuringZooms": true,
"studioSound": false,
"subtitlesEnabled": true,
"systemAudioVolume": 1,
"thumbnailInpointMs": 12000,
"transcriptsEnabled": true,
"viewCountEnabled": true,
"zoomAnimationStyle": "moderate"
}
}
}
}{
"docsUrl": "https://docs.tella.com/",
"error": "bad_request",
"message": "The request was malformed or contained invalid parameters."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unauthorized",
"message": "Authentication is required. Provide a valid API key."
}{
"docsUrl": "https://docs.tella.com/",
"error": "forbidden",
"message": "You don't have permission to access this resource."
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_found",
"message": "The requested resource was not found."
}{
"docsUrl": "https://docs.tella.com/",
"error": "conflict",
"message": "The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles."
}{
"docsUrl": "https://docs.tella.com/",
"error": "rate_limited",
"message": "You have exceeded the rate limit. Please slow down."
}{
"docsUrl": "https://docs.tella.com/",
"error": "server_error",
"message": "An unexpected error occurred"
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_implemented",
"message": "The requested operation is not implemented."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unavailable",
"message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}Authorizations
API key obtained from your Tella account settings
Path Parameters
Unique video identifier
"vid_abc123def456"
Query Parameters
Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned.
"scn_abc123,scn_def456"
Comma-separated details to include: all, settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words. Default: none.
"layouts,zooms,words"
Response
The video's edit state
A compact video timeline with optional video-level and clip-level details
Complete clip outline in playback order
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
0 <= x <= 90071992547409910 <= x <= 90071992547409910 <= x <= 90071992547409910 <= x <= 90071992547409910 <= x <= 90071992547409910 <= x <= 90071992547409910 <= x <= 9007199254740991Number of transcript words on the clip playback timeline, including hidden words. Null when transcript data could not be read.
0 <= x <= 90071992547409910 <= x <= 9007199254740991Clip playback duration in ms, with cuts removed
x >= 0-9007199254740991 <= x <= 9007199254740991Clip start time in ms on the complete video timeline
x >= 0Detail categories included in this response
settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words Minimal video timeline summary
Hide child attributes
Hide child attributes
"16:9"
5000Total playback duration in ms
x >= 0ISO-8601 timestamp of the video version represented
Present only when at least one detail category is requested
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Clip background. Use type = 'solid' with color, type = 'image' or 'video' with sourceId (from POST /v1/sources) or an exact catalog URL from GET /v1/backgrounds, or type = 'gradient' with gradientColor1, gradientColor2, gradientAngle.
Hide child attributes
Hide child attributes
Background variant. shaderGradient is read-only: responses include its two colors but no angle. Echoing the unchanged background preserves it; creating or modifying a shaderGradient through this API is not supported.
solid, gradient, image, video, shaderGradient "solid"
Hex color string. Required when type = 'solid'.
"#000000ff"
Linear gradient angle in degrees. Required when type = 'gradient'.
-9007199254740991 <= x <= 900719925474099145
Hex color string. Required when type = 'gradient'.
"#ff0080ff"
Hex color string. Required when type = 'gradient'.
"#7928caff"
Hosted image URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.
Source ID from POST /v1/sources (kind: image for type = 'image', kind: video for type = 'video'). Required for image/video backgrounds unless using an exact URL from GET /v1/backgrounds. Input-only.
"su_abc123"
Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.
x >= 012.4
Hosted video URL. Present in responses and accepted as input only when copied exactly from GET /v1/backgrounds; otherwise pass sourceId.
Hide child attributes
Hide child attributes
x >= 02000
Mask ID
"ly_abc123"
Strength from 0 to 1. Blur: 0 is the standard blur and 1 blurs three times as heavily; the content stays fully hidden at every value (defaults to 0). Highlight: how dark the area outside the highlight goes, 0 = no dimming, 1 = black (defaults to 0.7).
0 <= x <= 10.7
Start time in ms on the clip's playback timeline (cuts applied)
x >= 01000
blur, highlight "blur"
Raw cut definitions in ms of the source recording, matching get_clip
Hide child attributes
Hide child attributes
x >= 02000
Mask ID
"ly_abc123"
Strength from 0 to 1. Blur: 0 is the standard blur and 1 blurs three times as heavily; the content stays fully hidden at every value (defaults to 0). Highlight: how dark the area outside the highlight goes, 0 = no dimming, 1 = black (defaults to 0.7).
0 <= x <= 10.7
Start time in ms on the clip's playback timeline (cuts applied)
x >= 01000
blur, highlight "blur"
How a clip composes its layers, which determines the set of layouts it accepts: basicSubject (screen-only), cameraSubject (camera-only), or combi (camera + presentation).
basicSubject, cameraSubject, combi "combi"
Hide child attributes
Hide child attributes
Layout ID
B-roll media on this layout — one entry per filled slot (screen and/or camera). Empty on the base layout and on layouts whose underlying section carries no media. Each entry's slot says which slot it fills.
Hide child attributes
Hide child attributes
image, video Image height in pixels (image media only).
-9007199254740991 <= x <= 9007199254740991Hosted image URL, for image media. Read-only: not accepted as input — pass sourceId instead.
Which slot the media fills: screen (the subject/main frame, the default) or camera (the bubble/presentation slot — a media bubble over the recording behind it). A camera slot requires a layout that renders the camera (e.g. camera-bubble, side-by-side, tv-presenter).
screen, camera Source ID the media was created from. Absent for image media added in the editor.
Image width in pixels (image media only).
-9007199254740991 <= x <= 9007199254740991The crop of the clip's screen recording while this layout shows — the layout's own crop, else the clip's. Absent when the recording is uncropped.
Hide child attributes
Hide child attributes
Pixels of the screen recording removed from its bottom edge
x >= 0Pixels of the screen recording removed from its left edge
x >= 0Pixels of the screen recording removed from its right edge
x >= 0Pixels of the screen recording removed from its top edge
x >= 0Layout duration in ms. Omitted for clip-spanning layouts.
x >= 05000
True when this layout follows the clip's base layout: updating the base layout changes it too, so it needs no update of its own. False when it has its own layout. Absent on the base layout itself.
Structured layout for this section. Custom layouts, whether arranged in the editor or written through the API, report their geometry as kind: custom. Null only for internal layouts outside the public vocabulary.
- Fullscreen
- Middle
- Side by Side
- TV Presenter
- Cut Out
- Camera Bubble
- Camera Only
- Screen Only
- Custom
Hide child attributes
Hide child attributes
fullscreen Only honoured for basic-subject clips (Tella renders the screen fullscreen). Defaults to cover.
cover, letterbox Only honoured for camera-subject clips: regular (default) is plain fullscreen, stretch stretches the subject. Ignored on basic-subject clips.
regular, stretch The camera's pop-out while this layout shows. Absent when it is off.
Hide child attributes
Hide child attributes
How far the frame shrinks below the presenter, as a fraction of the camera slot (0–0.5). Defaults to 0.22.
0 <= x <= 0.5What fills the frame behind the presenter: original keeps the camera feed, color paints color. Defaults to original.
original, color Frame fill when background is color, as #RRGGBB or #RRGGBBAA. Defaults to #6366F1.
^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$Outline colour as #RRGGBB or #RRGGBBAA. Defaults to #FFFFFF.
^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$Outline around the frame as a fraction of its width (0–0.05); 0 draws none. Defaults to 0.
0 <= x <= 0.05Layout start time in ms on the clip's playback timeline (cuts applied). Omitted for clip-spanning layouts.
x >= 00
Transition into this layout. Omitted on the base layout, or when the section uses an internal style not exposed via the public API.
spring, hardCut Clip microphone volume override: a number when overridden, null when following the video, absent when there is no microphone audio
0 <= x <= 2Hide child attributes
Hide child attributes
Where the overlay sits relative to the presenter on a clip with a camera layout: front paints over everything, behind_presenter tucks it behind the cut-out presenter but above the clip background and screen. New overlays start on front. Without a camera in the layout the overlay paints in front either way.
front, behind_presenter "behind_presenter"
Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning.
x >= 05000
Overlay ID
"ly_abc123"
Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
x >= 01000
Intro/outro animation: smooth fades the overlay in at its start and out at its end, hard_cut pops it in and out. New overlays start on hard_cut.
smooth, hard_cut "hard_cut"
image, video "image"
Stacking position among the clip's image, video and text overlays: 0 is the backmost. depth applies first — a behind_presenter overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number.
0 <= x <= 90071992547409910
Hosted image URL, for image overlays. Read-only: not accepted as input — pass sourceId instead.
"Logo"
Source ID the overlay was created from.
"su_abc123"
Hide child attributes
Hide child attributes
x >= 03000
Sound effect ID
"ly_abc123"
Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
x >= 01000
Playback volume (1 = original).
1
"Whoosh"
"su_abc123"
Effective Studio Sound state: the video-level switch minus this clip's opt-out
Clip system audio override: a number when overridden, null when following the video, absent when there is no system audio
0 <= x <= 2Hide child attributes
Hide child attributes
Background behind the text. Overlays with no visible box report a solid #00000000.
Hide child attributes
Hide child attributes
Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
Background variant. Text overlays take a solid background; the other ClipBackground variants are not supported behind text.
solid "solid"
Shape of the solid background behind the text.
none, regular, squircle "squircle"
Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#FFFFFFFF"
Where the overlay sits relative to the presenter on a clip with a camera layout: front paints over everything, behind_presenter tucks it behind the cut-out presenter but above the clip background and screen. New overlays start on front. Without a camera in the layout the overlay paints in front either way.
front, behind_presenter "behind_presenter"
Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning.
x >= 05000
The overlay's font family. Normally one of the catalog families accepted on write, but overlays created before that catalog can report another bundled family, such as Graphik.
"Inter"
Font size in artboard pixels — absolute, like dimensions, so text keeps its size relative to the frame. Renderers scale it by their render scale factor.
x > 081
Variable-font weight axis — 100 (thin) to 900 (black).
500
Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded.
100
Text overlay ID
"ly_abc123"
Color of the outline (stroke) drawn around the letters, or null for no outline.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#000000FF"
Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters.
none, subtle, deep "subtle"
Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
x >= 01000
"Welcome back"
Horizontal alignment of the text inside its overlay box.
left, center, right "center"
Intro/outro animation: smooth fades the text in at its start and out at its end, hard_cut pops it in and out. New text overlays start on hard_cut.
smooth, hard_cut "hard_cut"
Stacking position among the clip's image, video and text overlays: 0 is the backmost. depth applies first — a behind_presenter overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number.
0 <= x <= 90071992547409910
Words in ms on the clip playback timeline. Includes hidden words so indices remain usable with transcript editing endpoints. Null when transcript data could not be read.
Hide child attributes
Hide child attributes
Whether a subtitle break is forced after this word, so the next word always starts a new subtitle block
false
Word end time, in ms on the clip's playback timeline
x >= 01800
Whether the word is hidden by an edit
false
Stable index of the word in the source recording
0 <= x <= 900719925474099112
Whether this word's subtitle block is kept together with the next word across punctuation and pauses. The lines-per-block limit still applies and breakAfter wins.
false
Word start time, in ms on the clip's playback timeline
x >= 01500
Word text
"Hello"
Hide child attributes
Hide child attributes
Duration in ms of playback. 0 when the zoom's footage is entirely cut out.
x >= 02000
Zoom ID
"ef_abc123"
Start time in ms on the clip's playback timeline (cuts applied)
x >= 01000
manualZoom zooms into a fixed focusPoint on the screen. trackingZoom automatically follows the cursor in the screen recording.
manualZoom, trackingZoom "manualZoom"
Point on the zoomed footage to zoom into, expressed as percentages of its dimensions. Required for manualZoom; ignored for trackingZoom.
Hide child attributes
Hide child attributes
Horizontal position on the screen frame (0-100). 0 = left edge.
0 <= x <= 10050
Vertical position on the screen frame (0-100). 0 = top edge.
0 <= x <= 10050
Magnification factor (1 = no zoom, 3.5 = max).
1 <= x <= 3.52
Hide child attributes
Hide child attributes
One video-wide track that loops over the whole video and is included in exports
Hide child attributes
Hide child attributes
Audio track duration in milliseconds
x > 0180036
Optional display name for the track
"Calm Product Tour"
HTTPS URL of the audio track
^https:\/\/.*"https://ucarecdn.com/example-track/"
Track volume from 0 (silent) to 1 (full volume)
0 <= x <= 10.2
Hide child attributes
Hide child attributes
Chapter description
5000"Overview of what we'll cover"
Chapter start time in seconds
x >= 00
Chapter title
1 - 255"Introduction"
Video playback and access settings
Hide child attributes
Hide child attributes
Restrict embedding to these domains only (Premium feature). Empty array allows all domains.
["example.com", "mysite.org"]
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.
1"Inter"
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.
40 <= x <= 20064
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.
100 <= x <= 1000500
How subtitle text is grouped: sentence chunks or one word at a time.
chunked, singleWord "chunked"
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.
0 <= x <= 31
Subtitle text size. Applies if subtitles are enabled on the video.
small, medium, large "medium"
Subtitle style. Applies if subtitles are enabled on the video. Background, shadow, and outline colors and toggles are available on every style.
- Backdrop
- Highlight
- Mono
- Cannes
- Classic
Hide child attributes
Hide child attributes
Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
backdrop Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
Text color of the spoken word when highlightMode is background. Defaults to textColor.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
Spoken-word color. Omit to retain the legacy text-opacity progression.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
How the spoken word is emphasized. Defaults to text.
text, background, fadeRest Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#5E51F8FF"
Letter case applied to every caption word. Defaults to original.
original, uppercase, lowercase Show subtitles to viewers by default
true
Send email notifications for new comments
false
Allow viewers to comment
true
Animated cursor settings
Hide child attributes
Hide child attributes
Show a ripple on mouse clicks. Defaults off for new videos.
false
Fade the animated cursor out while inactive and back in when activity resumes.
false
Move the cursor back to its opening position at the end for cleaner loops.
false
Animated cursor size multiplier.
0.5 <= x <= 63.05
Smooth cursor movement. Defaults off for new videos.
false
Animated cursor artwork. mac is the pre-Tahoe style; macTahoe and macGoldenGate match those macOS generations; windows and touch use platform-specific artwork.
mac, macTahoe, macGoldenGate, windows, touch "macTahoe"
Custom thumbnail image URL
"https://example.com/custom-thumbnail.jpg"
How each clip enters from the previous one, unless the clip overrides it via its own transition.
smooth, hard_cut "hard_cut"
Default playback speed (0.5-2.0). Viewers can still adjust.
0.5 <= x <= 21
Allow viewers to download the video
true
How layout transitions animate, gentlest to snappiest. Zooms have their own zoomAnimationStyle. custom is a spring set outside the named styles.
gentlest, gentle, relaxed, moderate, brisk, snappy, snappiest, custom "moderate"
Current access level, including org for workspace-visible videos
public, private, org, password, embedonly "org"
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.
0 <= x <= 21
Blur fast zoom, pan, and cursor movement. Defaults on for new videos.
true
Show publish date on video page
true
Allow viewers to download raw source files
false
Allow search engines to index the video page
true
Shrink camera bubbles while a zoom is active. Defaults on.
true
Studio Sound (AI audio enhancement) master switch for the video. Individual clips can opt out via the clip's studioSound field.
false
Allow viewers to enable subtitles
true
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.
0 <= x <= 21
Time in ms on the video's playback timeline of the frame picked as the thumbnail (set via inpointMs). Null when the thumbnail is an uploaded image or the default. A picked frame leaves customThumbnailURL null, so check this field to verify it.
0 <= x <= 900719925474099112000
Show transcript panel to viewers
true
Show view count on video page
true
How zooms ease in, out, and between each other, gentlest to snappiest. Zooms follow layoutAnimationStyle until one is set. custom is a spring set outside the named styles.
gentlest, gentle, relaxed, moderate, brisk, snappy, snappiest, custom "moderate"
Was this page helpful?