curl --request POST \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"durationMs": 4503599627370596,
"layout": {
"kind": "fullscreen"
},
"media": {
"sourceId": "<string>",
"type": "image"
},
"startTimeMs": 4503599627370495
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts"
payload = {
"durationMs": 4503599627370596,
"layout": { "kind": "fullscreen" },
"media": {
"sourceId": "<string>",
"type": "image"
},
"startTimeMs": 4503599627370495
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
durationMs: 4503599627370596,
layout: {kind: 'fullscreen'},
media: {sourceId: '<string>', type: 'image'},
startTimeMs: 4503599627370495
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts', 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}/layouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'durationMs' => 4503599627370596,
'layout' => [
'kind' => 'fullscreen'
],
'media' => [
'sourceId' => '<string>',
'type' => 'image'
],
'startTimeMs' => 4503599627370495
]),
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}/layouts"
payload := strings.NewReader("{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}"
response = http.request(request)
puts response.read_body{
"layout": {
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"durationMs": 5000,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
}{
"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": "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."
}Add a layout to a clip
Adds a layout to a clip. Provide both startTimeMs and durationMs for a time-ranged layout, or omit both for a clip-spanning layout.
curl --request POST \
--url https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"durationMs": 4503599627370596,
"layout": {
"kind": "fullscreen"
},
"media": {
"sourceId": "<string>",
"type": "image"
},
"startTimeMs": 4503599627370495
}
'import requests
url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts"
payload = {
"durationMs": 4503599627370596,
"layout": { "kind": "fullscreen" },
"media": {
"sourceId": "<string>",
"type": "image"
},
"startTimeMs": 4503599627370495
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
durationMs: 4503599627370596,
layout: {kind: 'fullscreen'},
media: {sourceId: '<string>', type: 'image'},
startTimeMs: 4503599627370495
})
};
fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts', 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}/layouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'durationMs' => 4503599627370596,
'layout' => [
'kind' => 'fullscreen'
],
'media' => [
'sourceId' => '<string>',
'type' => 'image'
],
'startTimeMs' => 4503599627370495
]),
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}/layouts"
payload := strings.NewReader("{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"durationMs\": 4503599627370596,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\n}"
response = http.request(request)
puts response.read_body{
"layout": {
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"durationMs": 5000,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
}{
"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": "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."
}Authorizations
API key obtained from your Tella account settings
Path Parameters
Video identifier
"vid_abc123def456"
Clip identifier
"cl_xyz789ghi012"
Body
Add a layout to a clip
Optional. Provide together with startTimeMs for a time-ranged layout. Minimum 200ms.
200 <= x <= 9007199254740991Layout shape. May be omitted when media is provided to use the default full-frame B-roll layout.
- Fullscreen
- Middle
- Side by Side
- TV Presenter
- Camera Bubble
- Camera Only
- Screen Only
Show child attributes
Show child attributes
Optional media content to show during this layout. Only valid on time-ranged layouts.
- ClipMediaImage
- ClipMediaVideo
Show child attributes
Show child attributes
Optional. Provide together with durationMs for a time-ranged layout. In ms on the clip's playback timeline (cuts applied).
0 <= x <= 9007199254740991Optional. Only valid on time-ranged layouts. Defaults to the user's saved layout intro transition when omitted. The user's saved layout outro transition is applied when the following layout begins or resumes.
spring, hardCut Response
OK
A layout on a clip
A layout attached to a clip. Times are in ms on the clip's playback timeline (cuts applied). Internally the layout stays anchored to the footage, so it doesn't drift when cuts change later.
Show child attributes
Show child attributes
Related topics
Model Context Protocol (MCP)LayoutsMultiple layoutsAdd media (B-roll)Add a clip from an uploaded sourceWas this page helpful?