WIwithchima
Clips

Update a text overlay

Changed on

Update a text overlay's copy, font, color, timing, position, or dimensions. Only the fields you send are changed.

patch/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}

Request

Path parameters

idstring required

Video ID

clipIdstring required

Clip ID

textOverlayIdstring required

Text overlay ID

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

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

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

fontWeightnumber
fontWidthnumber
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

Restyle the overlay with a preset from GET /v1/text-presets; its text, timing and placement stay. Style fields sent alongside override the preset's values.

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

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

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

zIndexinteger

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. A value past the top moves the overlay to the front; the other overlays keep their relative order.

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
  },
  "fontFamily": "Inter",
  "fontId": "media_abc123def456",
  "letterSpacing": -0.02,
  "outline": "#000000FF",
  "point": {
    "xPct": 30,
    "yPct": 30
  },
  "presetId": "default:label",
  "shadow": "subtle",
  "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