curl --request PATCH \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"name": "<string>",
"startTimeMs": 4503599627370495,
"transition": "smooth",
"zIndex": 0
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}"
payload = {
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"name": "<string>",
"startTimeMs": 4503599627370495,
"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({
depth: 'behind_presenter',
durationMs: 4503599627370495,
name: '<string>',
startTimeMs: 4503599627370495,
transition: 'smooth',
zIndex: 0
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}', 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}/overlays/{overlayId}",
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([
'depth' => 'behind_presenter',
'durationMs' => 4503599627370495,
'name' => '<string>',
'startTimeMs' => 4503599627370495,
'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}/overlays/{overlayId}"
payload := strings.NewReader("{\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\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}/overlays/{overlayId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}")
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 \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}"
response = http.request(request)
puts response.read_body{
"overlay": {
"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"
}
}{
"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 an overlay
Update an overlay’s name, timing, position, or dimensions. Only the fields you send are changed.
curl --request PATCH \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"name": "<string>",
"startTimeMs": 4503599627370495,
"transition": "smooth",
"zIndex": 0
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}"
payload = {
"depth": "behind_presenter",
"durationMs": 4503599627370495,
"name": "<string>",
"startTimeMs": 4503599627370495,
"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({
depth: 'behind_presenter',
durationMs: 4503599627370495,
name: '<string>',
startTimeMs: 4503599627370495,
transition: 'smooth',
zIndex: 0
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}', 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}/overlays/{overlayId}",
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([
'depth' => 'behind_presenter',
'durationMs' => 4503599627370495,
'name' => '<string>',
'startTimeMs' => 4503599627370495,
'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}/overlays/{overlayId}"
payload := strings.NewReader("{\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\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}/overlays/{overlayId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}")
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 \"depth\": \"behind_presenter\",\n \"durationMs\": 4503599627370495,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495,\n \"transition\": \"smooth\",\n \"zIndex\": 0\n}"
response = http.request(request)
puts response.read_body{
"overlay": {
"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"
}
}{
"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
Overlay ID
Body
Update an existing overlay
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 <= 9007199254740991Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
0 <= x <= 9007199254740991Intro/outro animation: smooth fades the overlay 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
An overlay on a clip
An image or video overlay on a clip.
Hide 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"
Was this page helpful?