WIwithchima
Clips

Add a text overlay to a clip

Changed on

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

Path parameters

idstring required

Video identifier

Example:vid_abc123def456
clipIdstring required

Clip identifier

Example:cl_xyz789ghi012

Request body

backgroundPaddingnumber

Extra room around the text inside its background, as a fraction of the font size added on every side (0.5 at an 80px font adds 40px). 0 is the standard padding. No effect without a visible background.

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.

letterSpacingnumber

Tracking: space between letters, as a fraction of the font size (-0.05 at an 80px font pulls letters 4px closer; 0.1 spreads them 8px apart). Negative tightens; 0 is the font's own spacing.

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, tracking, background, background shape, background padding 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.

transition'smooth' | 'hard_cut'

How one thing gives way to the next: smooth eases across the change, hard_cut swaps instantly.

Example request

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

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"
    },
    "backgroundPadding": 0.25,
    "backgroundShape": "squircle",
    "color": "#FFFFFFFF",
    "depth": "behind_presenter",
    "depthChanges": [
      {
        "atMs": 1200,
        "depth": "behind_presenter"
      }
    ],
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "fontFamily": "Inter",
    "fontId": "media_abc123def456",
    "fontSize": 81,
    "fontWeight": 500,
    "fontWidth": 100,
    "id": "ly_abc123",
    "letterSpacing": -0.02,
    "outline": "#000000FF",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "shadow": "subtle",
    "startTimeMs": 1000,
    "text": "Welcome back",
    "textAlign": "center",
    "transition": "smooth"
  }
}

Changes

  • 0cc3fcd307adRevision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status

  • 0b2b8234a7dbRevision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status