Add a text overlay to a clip

curl --request POST \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "durationMs": 5000,
  "startTimeMs": 1000,
  "text": "Welcome back",
  "animation": {
    "intro": {
      "preset": "slide_up"
    },
    "outro": {
      "preset": "fade"
    }
  },
  "backgroundShape": "squircle",
  "color": "#FFFFFFFF",
  "depth": "behind_presenter",
  "fontFamily": "Inter",
  "fontId": "media_abc123def456",
  "fontSize": 81,
  "fontWeight": 500,
  "fontWidth": 100,
  "outline": "#000000FF",
  "presetId": "default:label",
  "shadow": "subtle",
  "textAlign": "center"
}
'

import requests

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

payload = {
    "durationMs": 5000,
    "startTimeMs": 1000,
    "text": "Welcome back",
    "animation": {
        "intro": { "preset": "slide_up" },
        "outro": { "preset": "fade" }
    },
    "backgroundShape": "squircle",
    "color": "#FFFFFFFF",
    "depth": "behind_presenter",
    "fontFamily": "Inter",
    "fontId": "media_abc123def456",
    "fontSize": 81,
    "fontWeight": 500,
    "fontWidth": 100,
    "outline": "#000000FF",
    "presetId": "default:label",
    "shadow": "subtle",
    "textAlign": "center"
}
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: 5000,
    startTimeMs: 1000,
    text: 'Welcome back',
    animation: {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}},
    backgroundShape: 'squircle',
    color: '#FFFFFFFF',
    depth: 'behind_presenter',
    fontFamily: 'Inter',
    fontId: 'media_abc123def456',
    fontSize: 81,
    fontWeight: 500,
    fontWidth: 100,
    outline: '#000000FF',
    presetId: 'default:label',
    shadow: 'subtle',
    textAlign: 'center'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-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}/text-overlays",
  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' => 5000,
    'startTimeMs' => 1000,
    'text' => 'Welcome back',
    'animation' => [
        'intro' => [
                'preset' => 'slide_up'
        ],
        'outro' => [
                'preset' => 'fade'
        ]
    ],
    'backgroundShape' => 'squircle',
    'color' => '#FFFFFFFF',
    'depth' => 'behind_presenter',
    'fontFamily' => 'Inter',
    'fontId' => 'media_abc123def456',
    'fontSize' => 81,
    'fontWeight' => 500,
    'fontWidth' => 100,
    'outline' => '#000000FF',
    'presetId' => 'default:label',
    'shadow' => 'subtle',
    'textAlign' => 'center'
  ]),
  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}/text-overlays"

	payload := strings.NewReader("{\n  \"durationMs\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\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}/text-overlays")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"durationMs\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays")

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\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\n}"

response = http.request(request)
puts response.read_body

{
  "textOverlay": {
    "animation": {
      "intro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "motionBlur": true,
      "outro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textIntro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textOutro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      }
    },
    "background": {
      "color": "#5E51F8FF",
      "type": "solid"
    },
    "backgroundShape": "squircle",
    "color": "#FFFFFFFF",
    "depth": "behind_presenter",
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "fontFamily": "Inter",
    "fontSize": 81,
    "fontWeight": 500,
    "fontWidth": 100,
    "id": "ly_abc123",
    "outline": "#000000FF",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "shadow": "subtle",
    "startTimeMs": 1000,
    "text": "Welcome back",
    "textAlign": "center",
    "transition": "hard_cut",
    "zIndex": 0,
    "fontId": "media_abc123def456"
  }
}

{
  "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."
}

POST

https://api.tella.com

videos

{id}

clips

{clipId}

text-overlays

Add a text overlay to a clip

curl --request POST \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "durationMs": 5000,
  "startTimeMs": 1000,
  "text": "Welcome back",
  "animation": {
    "intro": {
      "preset": "slide_up"
    },
    "outro": {
      "preset": "fade"
    }
  },
  "backgroundShape": "squircle",
  "color": "#FFFFFFFF",
  "depth": "behind_presenter",
  "fontFamily": "Inter",
  "fontId": "media_abc123def456",
  "fontSize": 81,
  "fontWeight": 500,
  "fontWidth": 100,
  "outline": "#000000FF",
  "presetId": "default:label",
  "shadow": "subtle",
  "textAlign": "center"
}
'

import requests

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

payload = {
    "durationMs": 5000,
    "startTimeMs": 1000,
    "text": "Welcome back",
    "animation": {
        "intro": { "preset": "slide_up" },
        "outro": { "preset": "fade" }
    },
    "backgroundShape": "squircle",
    "color": "#FFFFFFFF",
    "depth": "behind_presenter",
    "fontFamily": "Inter",
    "fontId": "media_abc123def456",
    "fontSize": 81,
    "fontWeight": 500,
    "fontWidth": 100,
    "outline": "#000000FF",
    "presetId": "default:label",
    "shadow": "subtle",
    "textAlign": "center"
}
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: 5000,
    startTimeMs: 1000,
    text: 'Welcome back',
    animation: {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}},
    backgroundShape: 'squircle',
    color: '#FFFFFFFF',
    depth: 'behind_presenter',
    fontFamily: 'Inter',
    fontId: 'media_abc123def456',
    fontSize: 81,
    fontWeight: 500,
    fontWidth: 100,
    outline: '#000000FF',
    presetId: 'default:label',
    shadow: 'subtle',
    textAlign: 'center'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-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}/text-overlays",
  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' => 5000,
    'startTimeMs' => 1000,
    'text' => 'Welcome back',
    'animation' => [
        'intro' => [
                'preset' => 'slide_up'
        ],
        'outro' => [
                'preset' => 'fade'
        ]
    ],
    'backgroundShape' => 'squircle',
    'color' => '#FFFFFFFF',
    'depth' => 'behind_presenter',
    'fontFamily' => 'Inter',
    'fontId' => 'media_abc123def456',
    'fontSize' => 81,
    'fontWeight' => 500,
    'fontWidth' => 100,
    'outline' => '#000000FF',
    'presetId' => 'default:label',
    'shadow' => 'subtle',
    'textAlign' => 'center'
  ]),
  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}/text-overlays"

	payload := strings.NewReader("{\n  \"durationMs\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\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}/text-overlays")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"durationMs\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays")

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\": 5000,\n  \"startTimeMs\": 1000,\n  \"text\": \"Welcome back\",\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"backgroundShape\": \"squircle\",\n  \"color\": \"#FFFFFFFF\",\n  \"depth\": \"behind_presenter\",\n  \"fontFamily\": \"Inter\",\n  \"fontId\": \"media_abc123def456\",\n  \"fontSize\": 81,\n  \"fontWeight\": 500,\n  \"fontWidth\": 100,\n  \"outline\": \"#000000FF\",\n  \"presetId\": \"default:label\",\n  \"shadow\": \"subtle\",\n  \"textAlign\": \"center\"\n}"

response = http.request(request)
puts response.read_body

{
  "textOverlay": {
    "animation": {
      "intro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "motionBlur": true,
      "outro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textIntro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textOutro": {
        "blur": 0,
        "clip": false,
        "durationMs": 500,
        "easing": {
          "curve": "slow_down",
          "intensity": 0.5,
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveX": 0,
        "moveY": -0.5,
        "opacity": 0,
        "preset": "slide_up",
        "rotate": 0,
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      }
    },
    "background": {
      "color": "#5E51F8FF",
      "type": "solid"
    },
    "backgroundShape": "squircle",
    "color": "#FFFFFFFF",
    "depth": "behind_presenter",
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "fontFamily": "Inter",
    "fontSize": 81,
    "fontWeight": 500,
    "fontWidth": 100,
    "id": "ly_abc123",
    "outline": "#000000FF",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "shadow": "subtle",
    "startTimeMs": 1000,
    "text": "Welcome back",
    "textAlign": "center",
    "transition": "hard_cut",
    "zIndex": 0,
    "fontId": "media_abc123def456"
  }
}

{
  "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

Authorization

string

header

required

API key obtained from your Tella account settings

Path Parameters

string

required

Video identifier

Example:

"vid_abc123def456"

clipId

string

required

Clip identifier

Example:

"cl_xyz789ghi012"

Body

application/json

Add a text overlay to a clip. Nothing needs uploading — pass the copy directly. When point/dimensions are omitted, a centered box 60% of the artboard wide and 25% tall is used.

durationMs

integer

required

Required range: 0 < x <= 9007199254740991

Example:

5000

startTimeMs

integer

required

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

Required range: 0 <= x <= 9007199254740991

Example:

1000

text

string

required

Minimum string length: 1

Example:

"Welcome back"

animation

object

How the overlay enters and leaves; when set it replaces transition. Each side describes the hidden state the overlay moves from on the way in and back to on the way out. An omitted side stays as it is. {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}} is a complete animation; on text, {textIntro: {preset: 'slide_up', text: {unit: 'words'}}} brings the words in one by one.

Hide child attributes

animation.intro

object | null

How the whole overlay enters, or null to appear instantly. Takes no text. Omit to keep the current intro.

Hide child attributes

animation.intro.blur

number

Blur of the hidden state in pixels.

Required range: 0 <= x <= 200

animation.intro.clip

boolean

Clip the motion to the overlay's box, so it wipes in like a mask.

animation.intro.durationMs

number

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.

Required range: 50 <= x <= 5000

animation.intro.easing

object

How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.

Hide child attributes

animation.intro.easing.curve

enum<string>

required

How a side accelerates. linear keeps one speed. smooth, natural, slow_down, accelerate, elastic, bounce, overshoot, impulse and swing are shaped by intensity. custom follows bezier, spring follows spring.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

animation.intro.easing.bezier

number[]

For custom: the handles. Defaults to the side's current curve.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

animation.intro.easing.intensity

number

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.

Required range: 0 <= x <= 1

animation.intro.easing.spring

object

For spring: its physics. Defaults to stiffness 200, damping 12, mass 1.

Hide child attributes

animation.intro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

animation.intro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

animation.intro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

animation.intro.moveX

number

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Required range: -10 <= x <= 10

animation.intro.moveY

number

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Required range: -10 <= x <= 10

animation.intro.opacity

number

Opacity of the hidden state, 0 to 1.

Required range: 0 <= x <= 1

animation.intro.preset

enum<string>

Start from a ready-made side; the other fields adjust it. Without it the side starts from what it is now; a new whole side starts still and a new text side from fade.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

animation.intro.rotate

number

Clockwise rotation of the hidden state in degrees.

Required range: -3600 <= x <= 3600

animation.intro.scale

number

Scale of the hidden state; 1 is its resting size.

Required range: 0 <= x <= 10

animation.intro.text

object

On textIntro/textOutro only: which units play the side, each in turn. Required on a new text side.

Hide child attributes

animation.intro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

animation.intro.text.delayMs

number

How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.

Required range: 0 <= x <= 2000

animation.intro.text.order

enum<string>

Which unit goes first. random uses the same shuffle every time. Defaults to forward.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

animation.intro.text.smoothing

enum<string>

Eases the delays across the units. Defaults to linear.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

animation.motionBlur

boolean

Blur the overlay along its motion while it moves, scales or turns. Defaults to true.

animation.outro

object | null

How the whole overlay leaves, or null to disappear instantly. Takes no text. Omit to keep the current outro.

Hide child attributes

animation.outro.blur

number

Blur of the hidden state in pixels.

Required range: 0 <= x <= 200

animation.outro.clip

boolean

Clip the motion to the overlay's box, so it wipes in like a mask.

animation.outro.durationMs

number

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.

Required range: 50 <= x <= 5000

animation.outro.easing

object

How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.

Hide child attributes

animation.outro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

animation.outro.easing.bezier

number[]

For custom: the handles. Defaults to the side's current curve.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

animation.outro.easing.intensity

number

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.

Required range: 0 <= x <= 1

animation.outro.easing.spring

object

For spring: its physics. Defaults to stiffness 200, damping 12, mass 1.

Hide child attributes

animation.outro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

animation.outro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

animation.outro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

animation.outro.moveX

number

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Required range: -10 <= x <= 10

animation.outro.moveY

number

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Required range: -10 <= x <= 10

animation.outro.opacity

number

Opacity of the hidden state, 0 to 1.

Required range: 0 <= x <= 1

animation.outro.preset

enum<string>

Start from a ready-made side; the other fields adjust it. Without it the side starts from what it is now; a new whole side starts still and a new text side from fade.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

animation.outro.rotate

number

Clockwise rotation of the hidden state in degrees.

Required range: -3600 <= x <= 3600

animation.outro.scale

number

Scale of the hidden state; 1 is its resting size.

Required range: 0 <= x <= 10

animation.outro.text

object

On textIntro/textOutro only: which units play the side, each in turn. Required on a new text side.

Hide child attributes

animation.outro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

animation.outro.text.delayMs

number

How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.

Required range: 0 <= x <= 2000

animation.outro.text.order

enum<string>

Which unit goes first. random uses the same shuffle every time. Defaults to forward.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

animation.outro.text.smoothing

enum<string>

Eases the delays across the units. Defaults to linear.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

animation.textIntro

object | null

Text overlays only: how its letters, words or lines enter, one after another, or null for none. Plays alongside intro: both start together.

Hide child attributes

animation.textIntro.blur

number

Blur of the hidden state in pixels.

Required range: 0 <= x <= 200

animation.textIntro.clip

boolean

Clip the motion to the overlay's box, so it wipes in like a mask.

animation.textIntro.durationMs

number

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.

Required range: 50 <= x <= 5000

animation.textIntro.easing

object

How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.

Hide child attributes

animation.textIntro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

animation.textIntro.easing.bezier

number[]

For custom: the handles. Defaults to the side's current curve.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

animation.textIntro.easing.intensity

number

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.

Required range: 0 <= x <= 1

animation.textIntro.easing.spring

object

For spring: its physics. Defaults to stiffness 200, damping 12, mass 1.

Hide child attributes

animation.textIntro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

animation.textIntro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

animation.textIntro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

animation.textIntro.moveX

number

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Required range: -10 <= x <= 10

animation.textIntro.moveY

number

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Required range: -10 <= x <= 10

animation.textIntro.opacity

number

Opacity of the hidden state, 0 to 1.

Required range: 0 <= x <= 1

animation.textIntro.preset

enum<string>

Start from a ready-made side; the other fields adjust it. Without it the side starts from what it is now; a new whole side starts still and a new text side from fade.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

animation.textIntro.rotate

number

Clockwise rotation of the hidden state in degrees.

Required range: -3600 <= x <= 3600

animation.textIntro.scale

number

Scale of the hidden state; 1 is its resting size.

Required range: 0 <= x <= 10

animation.textIntro.text

object

On textIntro/textOutro only: which units play the side, each in turn. Required on a new text side.

Hide child attributes

animation.textIntro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

animation.textIntro.text.delayMs

number

How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.

Required range: 0 <= x <= 2000

animation.textIntro.text.order

enum<string>

Which unit goes first. random uses the same shuffle every time. Defaults to forward.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

animation.textIntro.text.smoothing

enum<string>

Eases the delays across the units. Defaults to linear.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

animation.textOutro

object | null

Text overlays only: how its letters, words or lines leave, one after another, or null for none. Plays alongside outro: both end together.

Hide child attributes

animation.textOutro.blur

number

Blur of the hidden state in pixels.

Required range: 0 <= x <= 200

animation.textOutro.clip

boolean

Clip the motion to the overlay's box, so it wipes in like a mask.

animation.textOutro.durationMs

number

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.

Required range: 50 <= x <= 5000

animation.textOutro.easing

object

How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.

Hide child attributes

animation.textOutro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

animation.textOutro.easing.bezier

number[]

For custom: the handles. Defaults to the side's current curve.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

animation.textOutro.easing.intensity

number

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.

Required range: 0 <= x <= 1

animation.textOutro.easing.spring

object

For spring: its physics. Defaults to stiffness 200, damping 12, mass 1.

Hide child attributes

animation.textOutro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

animation.textOutro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

animation.textOutro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

animation.textOutro.moveX

number

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Required range: -10 <= x <= 10

animation.textOutro.moveY

number

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Required range: -10 <= x <= 10

animation.textOutro.opacity

number

Opacity of the hidden state, 0 to 1.

Required range: 0 <= x <= 1

animation.textOutro.preset

enum<string>

Start from a ready-made side; the other fields adjust it. Without it the side starts from what it is now; a new whole side starts still and a new text side from fade.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

animation.textOutro.rotate

number

Clockwise rotation of the hidden state in degrees.

Required range: -3600 <= x <= 3600

animation.textOutro.scale

number

Scale of the hidden state; 1 is its resting size.

Required range: 0 <= x <= 10

animation.textOutro.text

object

On textIntro/textOutro only: which units play the side, each in turn. Required on a new text side.

Hide child attributes

animation.textOutro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

animation.textOutro.text.delayMs

number

How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.

Required range: 0 <= x <= 2000

animation.textOutro.text.order

enum<string>

Which unit goes first. random uses the same shuffle every time. Defaults to forward.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

animation.textOutro.text.smoothing

enum<string>

Eases the delays across the units. Defaults to linear.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

Example:

{
  "intro": { "preset": "slide_up" },
  "outro": { "preset": "fade" }
}

background

object

Background behind the text. Defaults to transparent.

Hide child attributes

background.color

string

required

Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#5E51F8FF"

background.type

enum<string>

required

Background variant. Text overlays take a solid background; the other ClipBackground variants are not supported behind text.

Available options:

solid

Example:

"solid"

backgroundShape

enum<string>

Defaults to none.

Available options:

none,

regular,

squircle

Example:

"squircle"

color

string

Defaults to white.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#FFFFFFFF"

depth

enum<string>

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.

Available options:

front,

behind_presenter

Example:

"behind_presenter"

dimensions

object

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.

Hide child attributes

dimensions.height

number

required

Required range: x > 0

Example:

540

dimensions.width

number

required

Required range: x > 0

Example:

960

fontFamily

enum<string>

One of Tella's catalog font families. Defaults to Inter. Anything outside the catalog is rejected rather than silently falling back; use fontId for an uploaded font.

Available options:

Inter,

Roboto Mono,

Archivo,

Barlow,

Caveat,

DM Sans,

Figtree,

Lora,

Merriweather,

Montserrat,

Nunito Sans,

Open Sans,

Oswald,

Playfair Display,

Poppins,

Raleway,

Roboto,

Roboto Flex,

Source Sans 3,

Space Grotesk

Example:

"Inter"

fontId

string

A custom font from the private or workspace library: the id of a font item from GET /v1/library?type=font, such as one uploaded with POST /v1/sources (kind: font) and POST /v1/library. Sets the overlay's font family to that font. Don't combine with fontFamily.

Minimum string length: 1

Example:

"media_abc123def456"

fontSize

number

Font size in artboard pixels. Defaults to 7.5% of the video's shorter side, which is the editor's default and readable at any canvas size.

Required range: x > 0

Example:

81

fontWeight

number

Variable-font weight axis — 100 (thin) to 900 (black), 500 by default. Values outside the chosen font's own axis range are clamped when rendered.

Required range: 1 <= x <= 1000

Example:

500

fontWidth

number

Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded, 100 by default. Values outside the chosen font's own axis range are clamped when rendered.

Required range: x > 0

Example:

100

outline

string | null

Defaults to no outline, or the preset's.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#000000FF"

point

object

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

Hide child attributes

point.xPct

number

required

Example:

30

point.yPct

number

required

Example:

30

presetId

string

A preset from GET /v1/text-presets — default:<id> for a built-in style or a saved preset's ID. Supplies the font, weight, width, color, size, alignment, background, background shape and outline (not the shadow); any of those fields sent alongside overrides the preset's value.

Minimum string length: 1

Example:

"default:label"

shadow

enum<string>

Defaults to none.

Available options:

none,

subtle,

deep

Example:

"subtle"

textAlign

enum<string>

Defaults to center.

Available options:

left,

center,

right

Example:

"center"

Response

A text overlay on a clip

textOverlay

object

required

A text overlay on a clip. Unlike image and video overlays it references no source — the copy and its font live on the overlay itself.

Hide child attributes

textOverlay.animation

object | null

required

How the text enters and leaves, or null when it plays its transition.

Hide child attributes

textOverlay.animation.intro

object | null

required

How the whole overlay enters, or null when it appears instantly.

Hide child attributes

textOverlay.animation.intro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

textOverlay.animation.intro.clip

boolean

required

Clip the motion to the overlay's box, so it wipes in like a mask.

Example:

false

textOverlay.animation.intro.durationMs

integer

required

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

500

textOverlay.animation.intro.easing

object

required

Hide child attributes

textOverlay.animation.intro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

textOverlay.animation.intro.easing.intensity

number

required

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.

Required range: 0 <= x <= 1

Example:

0.5

textOverlay.animation.intro.easing.bezier

number[]

The custom curve's handles.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

textOverlay.animation.intro.easing.spring

object

The spring curve's physics.

Hide child attributes

textOverlay.animation.intro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

textOverlay.animation.intro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

textOverlay.animation.intro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

textOverlay.animation.intro.moveX

number

required

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Example:

0

textOverlay.animation.intro.moveY

number

required

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Example:

-0.5

textOverlay.animation.intro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

textOverlay.animation.intro.preset

enum<string> | null

required

The preset the side matches, or null once its motion is custom.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

textOverlay.animation.intro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

textOverlay.animation.intro.scale

number

required

Scale of the hidden state; 1 is its resting size.

Example:

1

textOverlay.animation.intro.text

object

The units a text side plays on, each in turn.

Hide child attributes

textOverlay.animation.intro.text.delayMs

integer

required

How long after one unit the next starts, in ms (0 to 2000).

Required range: 0 <= x <= 2000

Example:

100

textOverlay.animation.intro.text.order

enum<string>

required

Which unit goes first. random uses the same shuffle every time.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

textOverlay.animation.intro.text.smoothing

enum<string>

required

Eases the delays across the units: linear is an even step, the other curves bunch the starts up at one end.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

textOverlay.animation.intro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

textOverlay.animation.motionBlur

boolean

required

Blur the overlay along its motion while it moves, scales or turns.

Example:

true

textOverlay.animation.outro

object | null

required

How the whole overlay leaves, or null when it disappears instantly.

Hide child attributes

textOverlay.animation.outro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

textOverlay.animation.outro.clip

boolean

required

Clip the motion to the overlay's box, so it wipes in like a mask.

Example:

false

textOverlay.animation.outro.durationMs

integer

required

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

500

textOverlay.animation.outro.easing

object

required

Hide child attributes

textOverlay.animation.outro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

textOverlay.animation.outro.easing.intensity

number

required

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.

Required range: 0 <= x <= 1

Example:

0.5

textOverlay.animation.outro.easing.bezier

number[]

The custom curve's handles.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

textOverlay.animation.outro.easing.spring

object

The spring curve's physics.

Hide child attributes

textOverlay.animation.outro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

textOverlay.animation.outro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

textOverlay.animation.outro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

textOverlay.animation.outro.moveX

number

required

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Example:

0

textOverlay.animation.outro.moveY

number

required

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Example:

-0.5

textOverlay.animation.outro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

textOverlay.animation.outro.preset

enum<string> | null

required

The preset the side matches, or null once its motion is custom.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

textOverlay.animation.outro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

textOverlay.animation.outro.scale

number

required

Scale of the hidden state; 1 is its resting size.

Example:

1

textOverlay.animation.outro.text

object

The units a text side plays on, each in turn.

Hide child attributes

textOverlay.animation.outro.text.delayMs

integer

required

How long after one unit the next starts, in ms (0 to 2000).

Required range: 0 <= x <= 2000

Example:

100

textOverlay.animation.outro.text.order

enum<string>

required

Which unit goes first. random uses the same shuffle every time.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

textOverlay.animation.outro.text.smoothing

enum<string>

required

Eases the delays across the units: linear is an even step, the other curves bunch the starts up at one end.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

textOverlay.animation.outro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

textOverlay.animation.textIntro

object | null

required

How a text overlay's letters, words or lines enter, one after another, while intro plays on the whole box. Null when they don't.

Hide child attributes

textOverlay.animation.textIntro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

textOverlay.animation.textIntro.clip

boolean

required

Clip the motion to the overlay's box, so it wipes in like a mask.

Example:

false

textOverlay.animation.textIntro.durationMs

integer

required

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

500

textOverlay.animation.textIntro.easing

object

required

Hide child attributes

textOverlay.animation.textIntro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

textOverlay.animation.textIntro.easing.intensity

number

required

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.

Required range: 0 <= x <= 1

Example:

0.5

textOverlay.animation.textIntro.easing.bezier

number[]

The custom curve's handles.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

textOverlay.animation.textIntro.easing.spring

object

The spring curve's physics.

Hide child attributes

textOverlay.animation.textIntro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

textOverlay.animation.textIntro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

textOverlay.animation.textIntro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

textOverlay.animation.textIntro.moveX

number

required

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Example:

0

textOverlay.animation.textIntro.moveY

number

required

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Example:

-0.5

textOverlay.animation.textIntro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

textOverlay.animation.textIntro.preset

enum<string> | null

required

The preset the side matches, or null once its motion is custom.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

textOverlay.animation.textIntro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

textOverlay.animation.textIntro.scale

number

required

Scale of the hidden state; 1 is its resting size.

Example:

1

textOverlay.animation.textIntro.text

object

The units a text side plays on, each in turn.

Hide child attributes

textOverlay.animation.textIntro.text.delayMs

integer

required

How long after one unit the next starts, in ms (0 to 2000).

Required range: 0 <= x <= 2000

Example:

100

textOverlay.animation.textIntro.text.order

enum<string>

required

Which unit goes first. random uses the same shuffle every time.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

textOverlay.animation.textIntro.text.smoothing

enum<string>

required

Eases the delays across the units: linear is an even step, the other curves bunch the starts up at one end.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

textOverlay.animation.textIntro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

textOverlay.animation.textOutro

object | null

required

How a text overlay's letters, words or lines leave, one after another, while outro plays on the whole box. Null when they don't.

Hide child attributes

textOverlay.animation.textOutro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

textOverlay.animation.textOutro.clip

boolean

required

Clip the motion to the overlay's box, so it wipes in like a mask.

Example:

false

textOverlay.animation.textOutro.durationMs

integer

required

How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

500

textOverlay.animation.textOutro.easing

object

required

Hide child attributes

textOverlay.animation.textOutro.easing.curve

enum<string>

required

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

bounce,

overshoot,

impulse,

swing,

custom,

spring

Example:

"slow_down"

textOverlay.animation.textOutro.easing.intensity

number

required

How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.

Required range: 0 <= x <= 1

Example:

0.5

textOverlay.animation.textOutro.easing.bezier

number[]

The custom curve's handles.

Required array length: 4 elements

Required range: 0 <= x <= 1

Example:

[0.25, 0.1, 0.25, 1]

textOverlay.animation.textOutro.easing.spring

object

The spring curve's physics.

Hide child attributes

textOverlay.animation.textOutro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

textOverlay.animation.textOutro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

textOverlay.animation.textOutro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

textOverlay.animation.textOutro.moveX

number

required

Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.

Example:

0

textOverlay.animation.textOutro.moveY

number

required

Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.

Example:

-0.5

textOverlay.animation.textOutro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

textOverlay.animation.textOutro.preset

enum<string> | null

required

The preset the side matches, or null once its motion is custom.

Available options:

fade,

slide_up,

slide_down,

slide_left,

slide_right,

mask_up,

mask_down,

grow,

shrink,

blur,

blur_slide_up

Example:

"slide_up"

textOverlay.animation.textOutro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

textOverlay.animation.textOutro.scale

number

required

Scale of the hidden state; 1 is its resting size.

Example:

1

textOverlay.animation.textOutro.text

object

The units a text side plays on, each in turn.

Hide child attributes

textOverlay.animation.textOutro.text.delayMs

integer

required

How long after one unit the next starts, in ms (0 to 2000).

Required range: 0 <= x <= 2000

Example:

100

textOverlay.animation.textOutro.text.order

enum<string>

required

Which unit goes first. random uses the same shuffle every time.

Available options:

forward,

backward,

center,

edges,

random

Example:

"forward"

textOverlay.animation.textOutro.text.smoothing

enum<string>

required

Eases the delays across the units: linear is an even step, the other curves bunch the starts up at one end.

Available options:

linear,

smooth,

natural,

slow_down,

accelerate,

elastic,

overshoot,

impulse,

swing

Example:

"linear"

textOverlay.animation.textOutro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

textOverlay.background

object

required

Background behind the text. Overlays with no visible box report a solid #00000000.

Hide child attributes

textOverlay.background.color

string

required

Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#5E51F8FF"

textOverlay.background.type

enum<string>

required

Background variant. Text overlays take a solid background; the other ClipBackground variants are not supported behind text.

Available options:

solid

Example:

"solid"

textOverlay.backgroundShape

enum<string>

required

Shape of the solid background behind the text.

Available options:

none,

regular,

squircle

Example:

"squircle"

textOverlay.color

string

required

Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#FFFFFFFF"

textOverlay.depth

enum<string>

required

Available options:

front,

behind_presenter

Example:

"behind_presenter"

textOverlay.dimensions

object

required

Hide child attributes

textOverlay.dimensions.height

number

required

Required range: x > 0

Example:

540

textOverlay.dimensions.width

number

required

Required range: x > 0

Example:

960

textOverlay.durationMs

number

required

Required range: x >= 0

Example:

5000

textOverlay.fontFamily

string

required

The overlay's font family. Normally one of the catalog families accepted on write, or a library font's family when fontId is set. Overlays created before that catalog can report another bundled family, such as Graphik.

Example:

"Inter"

textOverlay.fontSize

number

required

Font size in artboard pixels — absolute, like dimensions, so text keeps its size relative to the frame. Renderers scale it by their render scale factor.

Required range: x > 0

Example:

81

textOverlay.fontWeight

number

required

Variable-font weight axis — 100 (thin) to 900 (black).

Example:

500

textOverlay.fontWidth

number

required

Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded.

Example:

100

textOverlay.id

string

required

Text overlay ID

Example:

"ly_abc123"

textOverlay.outline

string | null

required

Color of the outline (stroke) drawn around the letters, or null for no outline.

Pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Example:

"#000000FF"

textOverlay.point

object

required

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

Hide child attributes

textOverlay.point.xPct

number

required

Example:

30

textOverlay.point.yPct

number

required

Example:

30

textOverlay.shadow

enum<string>

required

Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters.

Available options:

none,

subtle,

deep

Example:

"subtle"

textOverlay.startTimeMs

number

required

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

Required range: x >= 0

Example:

1000

textOverlay.text

string

required

Example:

"Welcome back"

textOverlay.textAlign

enum<string>

required

Horizontal alignment of the text inside its overlay box.

Available options:

left,

center,

right

Example:

"center"

textOverlay.transition

enum<string>

required

Intro/outro animation: smooth fades the text in at its start and out at its end, hard_cut pops it in and out. New text overlays start on hard_cut. An animation replaces it while set.

Available options:

smooth,

hard_cut

Example:

"hard_cut"

textOverlay.zIndex

integer

required

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.

Required range: 0 <= x <= 9007199254740991

Example:

0

textOverlay.fontId

string

The library font the overlay renders with (a font item's id), absent for a catalog family.

Example:

"media_abc123def456"

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Add a text overlay to a clip

Authorizations

Path Parameters

Body

Response