curl --request GET \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays"
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}/clips/{clipId}/shape-overlays', 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}/shape-overlays",
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}/clips/{clipId}/shape-overlays"
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}/clips/{clipId}/shape-overlays")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays")
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{
"shapeOverlays": [
{
"border": {
"color": "#FFFFFFFF",
"width": 1
},
"corners": "squircle",
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 1,
"fill": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"shaderGradientPreset": "Halo",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"id": "ly_abc123",
"name": "<string>",
"path": "<string>",
"point": {
"xPct": 30,
"yPct": 30
},
"shadow": "subtle",
"shapeType": "square",
"startTimeMs": 1,
"transition": "smooth",
"zIndex": 0,
"depthChanges": [
{
"atMs": 1200,
"depth": "behind_presenter"
}
]
}
]
}{
"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."
}List shape overlays on a clip
Returns the shape overlays (squares, circles, stars…) on a clip.
curl --request GET \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays"
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}/clips/{clipId}/shape-overlays', 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}/shape-overlays",
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}/clips/{clipId}/shape-overlays"
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}/clips/{clipId}/shape-overlays")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/shape-overlays")
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{
"shapeOverlays": [
{
"border": {
"color": "#FFFFFFFF",
"width": 1
},
"corners": "squircle",
"depth": "behind_presenter",
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 1,
"fill": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"shaderGradientPreset": "Halo",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"id": "ly_abc123",
"name": "<string>",
"path": "<string>",
"point": {
"xPct": 30,
"yPct": 30
},
"shadow": "subtle",
"shapeType": "square",
"startTimeMs": 1,
"transition": "smooth",
"zIndex": 0,
"depthChanges": [
{
"atMs": 1200,
"depth": "behind_presenter"
}
]
}
]
}{
"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 identifier
"vid_abc123def456"
Clip identifier
"cl_xyz789ghi012"
Response
OK
Shape overlays on a clip
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
How a square's corners are rounded.
none, regular, squircle "squircle"
Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. front paints over everything. behind_presenter paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on front. Without a presenter 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 >= 0What fills the shape, cut to its outline.
Hide child attributes
Hide child attributes
Background variant. ambient: the clip's screen, else its camera, heavily blurred; no other fields. shaderGradient: an animated gradient set by shaderGradientPreset; echoing a non-preset one unchanged keeps it.
solid, gradient, image, video, shaderGradient, ambient "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.
Animated gradient preset from GET /v1/backgrounds. Required when type = 'shaderGradient'.
"Halo"
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.
Shape overlay ID
"ly_abc123"
SVG path data in a 0–100 box, for shapeType path; null otherwise.
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"
The outline, stretched to fill the overlay box: a non-square box makes a rectangle or an oval. path draws the overlay's own path.
square, circle, triangle, diamond, star, hexagon, arrow, path x >= 0How one thing gives way to the next: smooth eases across the change, hard_cut swaps instantly.
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.
0 <= x <= 90071992547409910
Changes of depth over the overlay's own time, each held until the next: atMs after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind them (a ring orbiting their head, a title they step in front of). depth is where it starts. On updates, omit it to leave the changes as they are; [] removes them. Absent in responses while the overlay holds one depth.
Hide child attributes
Hide child attributes
Ms after the overlay starts.
x >= 01200
Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. front paints over everything. behind_presenter paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on front. Without a presenter the overlay paints in front either way.
front, behind_presenter "behind_presenter"
Was this page helpful?