Skip to main content
PATCH
/
v1
/
videos
/
{id}
/
clips
/
{clipId}
/
layouts
/
{layoutId}
Update a layout
curl --request PATCH \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts/{layoutId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "durationMs": 123,
  "layout": {
    "kind": "fullscreen"
  },
  "media": {
    "sourceId": "<string>",
    "type": "image"
  },
  "startTimeMs": 4503599627370495
}
'
import requests

url = "https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts/{layoutId}"

payload = {
"durationMs": 123,
"layout": { "kind": "fullscreen" },
"media": {
"sourceId": "<string>",
"type": "image"
},
"startTimeMs": 4503599627370495
}
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({
durationMs: 123,
layout: {kind: 'fullscreen'},
media: {sourceId: '<string>', type: 'image'},
startTimeMs: 4503599627370495
})
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/layouts/{layoutId}', 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/{layoutId}",
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([
'durationMs' => 123,
'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/{layoutId}"

payload := strings.NewReader("{\n \"durationMs\": 123,\n \"layout\": {\n \"kind\": \"fullscreen\"\n },\n \"media\": {\n \"sourceId\": \"<string>\",\n \"type\": \"image\"\n },\n \"startTimeMs\": 4503599627370495\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}/layouts/{layoutId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"durationMs\": 123,\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/{layoutId}")

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 \"durationMs\": 123,\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": [
      {
        "height": 0,
        "imageUrl": "<string>",
        "sourceId": "<string>",
        "width": 0
      }
    ],
    "durationMs": 5000,
    "layout": {
      "kind": "fullscreen"
    },
    "startTimeMs": 0
  }
}
{
"error": {
"code": "bad_request",
"doc_url": "https://tella.tv/docs/api-reference/errors#bad-request",
"message": "The request was malformed or contained invalid parameters."
}
}
{
"error": {
"code": "unauthorized",
"doc_url": "https://tella.tv/docs/api-reference/errors#unauthorized",
"message": "Authentication is required. Provide a valid API key."
}
}
{
"error": {
"code": "forbidden",
"doc_url": "https://tella.tv/docs/api-reference/errors#forbidden",
"message": "You don't have permission to access this resource."
}
}
{
"error": {
"code": "not_found",
"doc_url": "https://tella.tv/docs/api-reference/errors#not-found",
"message": "The requested resource was not found."
}
}
{
"error": {
"code": "unprocessable_entity",
"doc_url": "https://tella.tv/docs/api-reference/errors#unprocessable-entity",
"message": "The request was well-formed but contained semantic errors."
}
}
{
"error": {
"code": "rate_limit_exceeded",
"doc_url": "https://tella.tv/docs/api-reference/errors#rate-limit-exceeded",
"message": "You have exceeded the rate limit. Please slow down."
}
}
{
"error": {
"code": "internal_server_error",
"doc_url": "https://tella.tv/docs/api-reference/errors#internal-server-error",
"message": "An unexpected error occurred on the server."
}
}

Authorizations

Authorization
string
header
required

API key obtained from your Tella account settings

Path Parameters

id
string
required

Video ID

clipId
string
required

Clip ID

layoutId
string
required

Layout (section) ID

Body

application/json

Update an existing layout on a clip

durationMs
integer
Required range: x <= 9007199254740991
layout
Fullscreen · object

Single-layer fullscreen. Camera-subject clips take an optional style (regular/stretch); basic-subject clips take an optional screenFit.

media
ClipMediaImage · object

Replace the layout's media content. Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout.

startTimeMs
integer

Start time in ms on the clip's playback timeline (cuts applied)

Required range: 0 <= x <= 9007199254740991
transitionStyle
enum<string>

Only valid on time-ranged layouts; rejected on the base (clip-spanning) layout.

Available options:
spring,
hardCut

Response

OK

A layout on a clip

layout
object
required

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.