Add an overlay to a clip

curl --request POST \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "durationMs": 5000,
  "sourceId": "su_abc123",
  "startTimeMs": 1000,
  "animation": {
    "intro": {
      "preset": "slide_up"
    },
    "outro": {
      "preset": "fade"
    }
  },
  "depth": "behind_presenter",
  "name": "Logo"
}
'

import requests

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

payload = {
    "durationMs": 5000,
    "sourceId": "su_abc123",
    "startTimeMs": 1000,
    "animation": {
        "intro": { "preset": "slide_up" },
        "outro": { "preset": "fade" }
    },
    "depth": "behind_presenter",
    "name": "Logo"
}
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,
    sourceId: 'su_abc123',
    startTimeMs: 1000,
    animation: {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}},
    depth: 'behind_presenter',
    name: 'Logo'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/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}/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,
    'sourceId' => 'su_abc123',
    'startTimeMs' => 1000,
    'animation' => [
        'intro' => [
                'preset' => 'slide_up'
        ],
        'outro' => [
                'preset' => 'fade'
        ]
    ],
    'depth' => 'behind_presenter',
    'name' => 'Logo'
  ]),
  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"

	payload := strings.NewReader("{\n  \"durationMs\": 5000,\n  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\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}/overlays")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"durationMs\": 5000,\n  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/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  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\n}"

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

{
  "overlay": {
    "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"
        }
      }
    },
    "depth": "behind_presenter",
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "id": "ly_abc123",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "startTimeMs": 1000,
    "transition": "hard_cut",
    "type": "image",
    "zIndex": 0,
    "imageUrl": "<string>",
    "name": "Logo",
    "sourceId": "su_abc123"
  }
}

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

overlays

Add an overlay to a clip

curl --request POST \
  --url https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "durationMs": 5000,
  "sourceId": "su_abc123",
  "startTimeMs": 1000,
  "animation": {
    "intro": {
      "preset": "slide_up"
    },
    "outro": {
      "preset": "fade"
    }
  },
  "depth": "behind_presenter",
  "name": "Logo"
}
'

import requests

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

payload = {
    "durationMs": 5000,
    "sourceId": "su_abc123",
    "startTimeMs": 1000,
    "animation": {
        "intro": { "preset": "slide_up" },
        "outro": { "preset": "fade" }
    },
    "depth": "behind_presenter",
    "name": "Logo"
}
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,
    sourceId: 'su_abc123',
    startTimeMs: 1000,
    animation: {intro: {preset: 'slide_up'}, outro: {preset: 'fade'}},
    depth: 'behind_presenter',
    name: 'Logo'
  })
};

fetch('https://api.tella.com/v1/videos/{id}/clips/{clipId}/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}/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,
    'sourceId' => 'su_abc123',
    'startTimeMs' => 1000,
    'animation' => [
        'intro' => [
                'preset' => 'slide_up'
        ],
        'outro' => [
                'preset' => 'fade'
        ]
    ],
    'depth' => 'behind_presenter',
    'name' => 'Logo'
  ]),
  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"

	payload := strings.NewReader("{\n  \"durationMs\": 5000,\n  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\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}/overlays")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"durationMs\": 5000,\n  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tella.com/v1/videos/{id}/clips/{clipId}/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  \"sourceId\": \"su_abc123\",\n  \"startTimeMs\": 1000,\n  \"animation\": {\n    \"intro\": {\n      \"preset\": \"slide_up\"\n    },\n    \"outro\": {\n      \"preset\": \"fade\"\n    }\n  },\n  \"depth\": \"behind_presenter\",\n  \"name\": \"Logo\"\n}"

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

{
  "overlay": {
    "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"
        }
      }
    },
    "depth": "behind_presenter",
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "id": "ly_abc123",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "startTimeMs": 1000,
    "transition": "hard_cut",
    "type": "image",
    "zIndex": 0,
    "imageUrl": "<string>",
    "name": "Logo",
    "sourceId": "su_abc123"
  }
}

{
  "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 an image or video overlay to a clip. Upload the bytes via POST /v1/sources (kind: image or kind: video) and pass the sourceId; the overlay type follows the source's kind. When point/dimensions are omitted, a centered box is computed from the source.

durationMs

integer

required

Required range: 0 < x <= 9007199254740991

Example:

5000

sourceId

string

required

Source ID from POST /v1/sources (kind: image or kind: video). The overlay type follows the source's kind.

Example:

"su_abc123"

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

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

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

name

string

Example:

"Logo"

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

Response

An overlay on a clip

overlay

object

required

An image or video overlay on a clip.

Hide child attributes

overlay.animation

object | null

required

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

Hide child attributes

overlay.animation.intro

object | null

required

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

Hide child attributes

overlay.animation.intro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

overlay.animation.intro.clip

boolean

required

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

Example:

false

overlay.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

overlay.animation.intro.easing

object

required

Hide child attributes

overlay.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"

overlay.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

overlay.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]

overlay.animation.intro.easing.spring

object

The spring curve's physics.

Hide child attributes

overlay.animation.intro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

overlay.animation.intro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

overlay.animation.intro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

overlay.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

overlay.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

overlay.animation.intro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

overlay.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"

overlay.animation.intro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

overlay.animation.intro.scale

number

required

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

Example:

1

overlay.animation.intro.text

object

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

Hide child attributes

overlay.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

overlay.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"

overlay.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"

overlay.animation.intro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

overlay.animation.motionBlur

boolean

required

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

Example:

true

overlay.animation.outro

object | null

required

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

Hide child attributes

overlay.animation.outro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

overlay.animation.outro.clip

boolean

required

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

Example:

false

overlay.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

overlay.animation.outro.easing

object

required

Hide child attributes

overlay.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"

overlay.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

overlay.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]

overlay.animation.outro.easing.spring

object

The spring curve's physics.

Hide child attributes

overlay.animation.outro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

overlay.animation.outro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

overlay.animation.outro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

overlay.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

overlay.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

overlay.animation.outro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

overlay.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"

overlay.animation.outro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

overlay.animation.outro.scale

number

required

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

Example:

1

overlay.animation.outro.text

object

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

Hide child attributes

overlay.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

overlay.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"

overlay.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"

overlay.animation.outro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

overlay.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

overlay.animation.textIntro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

overlay.animation.textIntro.clip

boolean

required

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

Example:

false

overlay.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

overlay.animation.textIntro.easing

object

required

Hide child attributes

overlay.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"

overlay.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

overlay.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]

overlay.animation.textIntro.easing.spring

object

The spring curve's physics.

Hide child attributes

overlay.animation.textIntro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

overlay.animation.textIntro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

overlay.animation.textIntro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

overlay.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

overlay.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

overlay.animation.textIntro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

overlay.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"

overlay.animation.textIntro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

overlay.animation.textIntro.scale

number

required

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

Example:

1

overlay.animation.textIntro.text

object

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

Hide child attributes

overlay.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

overlay.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"

overlay.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"

overlay.animation.textIntro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

overlay.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

overlay.animation.textOutro.blur

number

required

Blur of the hidden state in pixels.

Example:

0

overlay.animation.textOutro.clip

boolean

required

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

Example:

false

overlay.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

overlay.animation.textOutro.easing

object

required

Hide child attributes

overlay.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"

overlay.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

overlay.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]

overlay.animation.textOutro.easing.spring

object

The spring curve's physics.

Hide child attributes

overlay.animation.textOutro.easing.spring.damping

number

required

Required range: 1 <= x <= 300

Example:

12

overlay.animation.textOutro.easing.spring.mass

number

required

Required range: 0.1 <= x <= 10

Example:

1

overlay.animation.textOutro.easing.spring.stiffness

number

required

Required range: 1 <= x <= 1000

Example:

200

overlay.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

overlay.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

overlay.animation.textOutro.opacity

number

required

Opacity of the hidden state, 0 to 1.

Example:

0

overlay.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"

overlay.animation.textOutro.rotate

number

required

Clockwise rotation of the hidden state in degrees.

Example:

0

overlay.animation.textOutro.scale

number

required

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

Example:

1

overlay.animation.textOutro.text

object

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

Hide child attributes

overlay.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

overlay.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"

overlay.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"

overlay.animation.textOutro.text.unit

enum<string>

required

What animates on its own.

Available options:

letters,

words,

lines

Example:

"words"

overlay.depth

enum<string>

required

Available options:

front,

behind_presenter

Example:

"behind_presenter"

overlay.dimensions

object

required

Hide child attributes

overlay.dimensions.height

number

required

Required range: x > 0

Example:

540

overlay.dimensions.width

number

required

Required range: x > 0

Example:

960

overlay.durationMs

number

required

Required range: x >= 0

Example:

5000

overlay.id

string

required

Overlay ID

Example:

"ly_abc123"

overlay.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

overlay.point.xPct

number

required

Example:

30

overlay.point.yPct

number

required

Example:

30

overlay.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

overlay.transition

enum<string>

required

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

Available options:

smooth,

hard_cut

Example:

"hard_cut"

overlay.type

enum<string>

required

Available options:

image,

video

Example:

"image"

overlay.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

overlay.imageUrl

string | null

Hosted image URL, for image overlays. Read-only: not accepted as input — pass sourceId instead.

overlay.name

string | null

Example:

"Logo"

overlay.sourceId

string | null

Source ID the overlay was created from.

Example:

"su_abc123"

Getting Started

Guides

MCP Tools

API Reference

Webhooks

Add an overlay to a clip

Authorizations

Path Parameters

Body

Response