Clips

Add a text overlay to a clip

Adds a text overlay to a clip. Nothing needs uploading — pass the copy directly. Font, color, position and size all fall back to the editor's defaults.

post/v1/videos/{id}/clips/{clipId}/text-overlays

Request

  • Base URL: https://api.tella.com
  • URL: https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays
  • Auth: HTTP bearer

Path parameters

idstring required

Video identifier

Example:vid_abc123def456
clipIdstring required

Clip identifier

Example:cl_xyz789ghi012

Request body

backgroundShape'none' | 'regular' | 'squircle'

Shape of the solid background behind the text.

colorstring

Defaults to white.

depth'front' | 'behind_presenter'

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.

durationMsinteger required
fontFamily'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'

One of Tella's catalog font families — the same list the editor's font picker offers.

fontIdstring

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.

fontSizenumber

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.

fontWeightnumber

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.

fontWidthnumber

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.

outlinestring nullable

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

presetIdstring

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.

shadow'none' | 'subtle' | 'deep'

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

startTimeMsinteger required

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

textstring required
textAlign'left' | 'center' | 'right'

Horizontal alignment of the text inside its overlay box.

Example request

{
  "animation": {
    "intro": {
      "preset": "slide_up"
    },
    "outro": {
      "preset": "fade"
    }
  },
  "background": {
    "color": "#5E51F8FF",
    "type": "solid"
  },
  "backgroundShape": "squircle",
  "color": "#FFFFFFFF",
  "depth": "behind_presenter",
  "dimensions": {
    "height": 540,
    "width": 960
  },
  "durationMs": 5000,
  "fontFamily": "Inter",
  "fontId": "media_abc123def456",
  "fontSize": 81,
  "fontWeight": 500,
  "fontWidth": 100,
  "outline": "#000000FF",
  "point": {
    "xPct": 30,
    "yPct": 30
  },
  "presetId": "default:label",
  "shadow": "subtle",
  "startTimeMs": 1000,
  "text": "Welcome back",
  "textAlign": "center"
}

Response

OK

Example response

{
  "textOverlay": {
    "animation": {
      "intro": {
        "durationMs": 500,
        "easing": {
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "curve": "slow_down",
          "intensity": 0.5,
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveY": -0.5,
        "preset": "slide_up",
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "motionBlur": true,
      "outro": {
        "durationMs": 500,
        "easing": {
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "curve": "slow_down",
          "intensity": 0.5,
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveY": -0.5,
        "preset": "slide_up",
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textIntro": {
        "durationMs": 500,
        "easing": {
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "curve": "slow_down",
          "intensity": 0.5,
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveY": -0.5,
        "preset": "slide_up",
        "scale": 1,
        "text": {
          "delayMs": 100,
          "order": "forward",
          "smoothing": "linear",
          "unit": "words"
        }
      },
      "textOutro": {
        "durationMs": 500,
        "easing": {
          "bezier": [
            0.25,
            0.1,
            0.25,
            1
          ],
          "curve": "slow_down",
          "intensity": 0.5,
          "spring": {
            "damping": 12,
            "mass": 1,
            "stiffness": 200
          }
        },
        "moveY": -0.5,
        "preset": "slide_up",
        "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",
    "fontId": "media_abc123def456",
    "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": "smooth"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.