Skip to main content
PATCH
/
v1
/
videos
/
{id}
/
clips
/
{clipId}
/
overlays
/
{overlayId}
Update an overlay
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 '
{
  "durationMs": 123,
  "name": "<string>",
  "startTimeMs": 4503599627370495
}
'
import requests

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

payload = {
"durationMs": 123,
"name": "<string>",
"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, name: '<string>', startTimeMs: 4503599627370495})
};

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([
'durationMs' => 123,
'name' => '<string>',
'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}/overlays/{overlayId}"

payload := strings.NewReader("{\n \"durationMs\": 123,\n \"name\": \"<string>\",\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}/overlays/{overlayId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"durationMs\": 123,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495\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 \"durationMs\": 123,\n \"name\": \"<string>\",\n \"startTimeMs\": 4503599627370495\n}"

response = http.request(request)
puts response.read_body
{
  "overlay": {
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "id": "ly_abc123",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "startTimeMs": 1000,
    "type": "image",
    "imageUrl": "<string>",
    "name": "Logo",
    "sourceId": "su_abc123"
  }
}
{
"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

overlayId
string
required

Overlay ID

Body

application/json

Update an existing overlay

dimensions
object

Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change.

durationMs
integer
Required range: x <= 9007199254740991
name
string
point
object

Top-left corner of the overlay, as a percentage of the story canvas (0-100). Relative so the anchor survives story ratio changes.

startTimeMs
integer

Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.

Required range: 0 <= x <= 9007199254740991

Response

OK

An overlay on a clip

overlay
object
required

An image or video overlay on a clip.