curl --request PATCH \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"fontFamily": "Inter",
"fontSize": 1,
"fontWeight": 500.5,
"fontWidth": 1,
"outline": "#000000FF",
"presetId": "default:label",
"shadow": "subtle",
"startTimeMs": 4503599627370495,
"text": "<string>",
"textAlign": "center",
"transition": "smooth",
"zIndex": 0
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}"
payload = {
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"fontFamily": "Inter",
"fontSize": 1,
"fontWeight": 500.5,
"fontWidth": 1,
"outline": "#000000FF",
"presetId": "default:label",
"shadow": "subtle",
"startTimeMs": 4503599627370495,
"text": "<string>",
"textAlign": "center",
"transition": "smooth",
"zIndex": 0
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
backgroundShape: 'squircle',
color: '#FFFFFFFF',
depth: 'behind_presenter',
durationMs: 4503599627370495,
fontFamily: 'Inter',
fontSize: 1,
fontWeight: 500.5,
fontWidth: 1,
outline: '#000000FF',
presetId: 'default:label',
shadow: 'subtle',
startTimeMs: 4503599627370495,
text: '<string>',
textAlign: 'center',
transition: 'smooth',
zIndex: 0
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}', 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}/clips/{clipId}/text-overlays/{textOverlayId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'backgroundShape' => 'squircle',
'color' => '#FFFFFFFF',
'depth' => 'behind_presenter',
'durationMs' => 4503599627370495,
'fontFamily' => 'Inter',
'fontSize' => 1,
'fontWeight' => 500.5,
'fontWidth' => 1,
'outline' => '#000000FF',
'presetId' => 'default:label',
'shadow' => 'subtle',
'startTimeMs' => 4503599627370495,
'text' => '<string>',
'textAlign' => 'center',
'transition' => 'smooth',
'zIndex' => 0
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}"
payload := strings.NewReader("{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}"
response = http.request(request)
puts response.read_body{
"textOverlay": {
"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
}
}{
"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."
}Update a text overlay
Update a text overlay’s copy, font, color, timing, position, or dimensions. Only the fields you send are changed.
curl --request PATCH \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"fontFamily": "Inter",
"fontSize": 1,
"fontWeight": 500.5,
"fontWidth": 1,
"outline": "#000000FF",
"presetId": "default:label",
"shadow": "subtle",
"startTimeMs": 4503599627370495,
"text": "<string>",
"textAlign": "center",
"transition": "smooth",
"zIndex": 0
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}"
payload = {
"backgroundShape": "squircle",
"color": "#FFFFFFFF",
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"fontFamily": "Inter",
"fontSize": 1,
"fontWeight": 500.5,
"fontWidth": 1,
"outline": "#000000FF",
"presetId": "default:label",
"shadow": "subtle",
"startTimeMs": 4503599627370495,
"text": "<string>",
"textAlign": "center",
"transition": "smooth",
"zIndex": 0
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
backgroundShape: 'squircle',
color: '#FFFFFFFF',
depth: 'behind_presenter',
durationMs: 4503599627370495,
fontFamily: 'Inter',
fontSize: 1,
fontWeight: 500.5,
fontWidth: 1,
outline: '#000000FF',
presetId: 'default:label',
shadow: 'subtle',
startTimeMs: 4503599627370495,
text: '<string>',
textAlign: 'center',
transition: 'smooth',
zIndex: 0
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}', 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}/clips/{clipId}/text-overlays/{textOverlayId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'backgroundShape' => 'squircle',
'color' => '#FFFFFFFF',
'depth' => 'behind_presenter',
'durationMs' => 4503599627370495,
'fontFamily' => 'Inter',
'fontSize' => 1,
'fontWeight' => 500.5,
'fontWidth' => 1,
'outline' => '#000000FF',
'presetId' => 'default:label',
'shadow' => 'subtle',
'startTimeMs' => 4503599627370495,
'text' => '<string>',
'textAlign' => 'center',
'transition' => 'smooth',
'zIndex' => 0
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}"
payload := strings.NewReader("{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"backgroundShape\": \"squircle\",\n \"color\": \"#FFFFFFFF\",\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"fontFamily\": \"Inter\",\n \"fontSize\": 1,\n \"fontWeight\": 500.5,\n \"fontWidth\": 1,\n \"outline\": \"#000000FF\",\n \"presetId\": \"default:label\",\n \"shadow\": \"subtle\",\n \"startTimeMs\": 4503599627370495,\n \"text\": \"<string>\",\n \"textAlign\": \"center\",\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}"
response = http.request(request)
puts response.read_body{
"textOverlay": {
"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
}
}{
"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
Video ID
Clip ID
Text overlay ID
Body
Update an existing text overlay
Background behind a text overlay, in the same object shape as a clip background.
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.
0 < x <= 9007199254740991One of Tella's catalog font families — the same list the editor's font picker offers.
Inter, Roboto Mono, Archivo, Barlow, Caveat, DM Sans, Figtree, Lora, Merriweather, Montserrat, Nunito Sans, Open Sans, Oswald, Playfair Display, Poppins, Raleway, Roboto, Roboto Flex, Source Sans 3, Space Grotesk "Inter"
Font size in artboard pixels.
x > 01 <= x <= 1000x > 0Set an outline color, or null to remove the outline.
^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$"#000000FF"
Restyle the overlay with a preset from GET /v1/text-presets; its text, timing and placement stay. Style fields sent alongside override the preset's values.
1"default:label"
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.
0 <= x <= 90071992547409911Horizontal 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.
smooth, hard_cut "smooth"
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. A value past the top moves the overlay to the front; the other overlays keep their relative order.
0 <= x <= 90071992547409910
Response
OK
A text overlay on a clip
A text overlay on a clip. Unlike image and video overlays it references no source — the copy and its font live on the overlay itself.
Hide 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
Was this page helpful?