---
title: "Update a text overlay"
method: PATCH
path: "/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}"
tags: ["Clips"]
---

# Update a text overlay

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

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/:id/clips/:clipId/text-overlays/:textOverlayId/patch.ts> (a function with typed inputs; its response is checked against the schema)

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

## Path parameters

- `id` string, required: Video ID
- `clipId` string, required: Clip ID
- `textOverlayId` string, required: Text overlay ID

## Request body

- UpdateClipTextOverlayRequest: Update an existing text overlay
  - `animation` OverlayAnimationInput: 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.
    - `intro` OverlayAnimationSideInput: One side of an overlay animation. A side starts from its `preset` (or from the side as it is) and the fields you give adjust it.
      - `blur` number: Blur of the hidden state in pixels.
      - `clip` boolean: Clip the motion to the overlay's box, so it wipes in like a mask.
      - `durationMs` number: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.
      - `easing` OverlayAnimationEasingInput: How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.
        - `bezier` union[]: For `custom`: the handles. Defaults to the side's current curve.
          - union
            - number
            - number
            - number
            - number
        - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
        - `intensity` number: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.
        - `spring` OverlayAnimationSpring: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
          - `damping` number, required
          - `mass` number, required
          - `stiffness` number, required
      - `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.
      - `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.
      - `opacity` number: Opacity of the hidden state, 0 to 1.
      - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up': A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
      - `rotate` number: Clockwise rotation of the hidden state in degrees.
      - `scale` number: Scale of the hidden state; 1 is its resting size.
      - `text` OverlayAnimationTextInput: On `textIntro`/`textOutro` only: which units play the side, each in turn. Required on a new text side.
        - `delayMs` number: How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.
        - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random': Which unit goes first. `random` uses the same shuffle every time. Defaults to `forward`.
        - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing': Eases the delays across the units. Defaults to `linear`.
        - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
    - `motionBlur` boolean: Blur the overlay along its motion while it moves, scales or turns. Defaults to true.
    - `outro` OverlayAnimationSideInput: One side of an overlay animation. A side starts from its `preset` (or from the side as it is) and the fields you give adjust it.
      - `blur` number: Blur of the hidden state in pixels.
      - `clip` boolean: Clip the motion to the overlay's box, so it wipes in like a mask.
      - `durationMs` number: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.
      - `easing` OverlayAnimationEasingInput: How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.
        - `bezier` union[]: For `custom`: the handles. Defaults to the side's current curve.
          - union
            - number
            - number
            - number
            - number
        - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
        - `intensity` number: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.
        - `spring` OverlayAnimationSpring: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
          - `damping` number, required
          - `mass` number, required
          - `stiffness` number, required
      - `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.
      - `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.
      - `opacity` number: Opacity of the hidden state, 0 to 1.
      - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up': A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
      - `rotate` number: Clockwise rotation of the hidden state in degrees.
      - `scale` number: Scale of the hidden state; 1 is its resting size.
      - `text` OverlayAnimationTextInput: On `textIntro`/`textOutro` only: which units play the side, each in turn. Required on a new text side.
        - `delayMs` number: How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.
        - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random': Which unit goes first. `random` uses the same shuffle every time. Defaults to `forward`.
        - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing': Eases the delays across the units. Defaults to `linear`.
        - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
    - `textIntro` OverlayAnimationSideInput: One side of an overlay animation. A side starts from its `preset` (or from the side as it is) and the fields you give adjust it.
      - `blur` number: Blur of the hidden state in pixels.
      - `clip` boolean: Clip the motion to the overlay's box, so it wipes in like a mask.
      - `durationMs` number: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.
      - `easing` OverlayAnimationEasingInput: How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.
        - `bezier` union[]: For `custom`: the handles. Defaults to the side's current curve.
          - union
            - number
            - number
            - number
            - number
        - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
        - `intensity` number: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.
        - `spring` OverlayAnimationSpring: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
          - `damping` number, required
          - `mass` number, required
          - `stiffness` number, required
      - `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.
      - `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.
      - `opacity` number: Opacity of the hidden state, 0 to 1.
      - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up': A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
      - `rotate` number: Clockwise rotation of the hidden state in degrees.
      - `scale` number: Scale of the hidden state; 1 is its resting size.
      - `text` OverlayAnimationTextInput: On `textIntro`/`textOutro` only: which units play the side, each in turn. Required on a new text side.
        - `delayMs` number: How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.
        - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random': Which unit goes first. `random` uses the same shuffle every time. Defaults to `forward`.
        - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing': Eases the delays across the units. Defaults to `linear`.
        - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
    - `textOutro` OverlayAnimationSideInput: One side of an overlay animation. A side starts from its `preset` (or from the side as it is) and the fields you give adjust it.
      - `blur` number: Blur of the hidden state in pixels.
      - `clip` boolean: Clip the motion to the overlay's box, so it wipes in like a mask.
      - `durationMs` number: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays. Defaults to 500.
      - `easing` OverlayAnimationEasingInput: How the side accelerates. Without it a new side slows down into place on the way in and speeds up on the way out.
        - `bezier` union[]: For `custom`: the handles. Defaults to the side's current curve.
          - union
            - number
            - number
            - number
            - number
        - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
        - `intensity` number: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it. Defaults to 0.5.
        - `spring` OverlayAnimationSpring: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
          - `damping` number, required
          - `mass` number, required
          - `stiffness` number, required
      - `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.
      - `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.
      - `opacity` number: Opacity of the hidden state, 0 to 1.
      - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up': A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
      - `rotate` number: Clockwise rotation of the hidden state in degrees.
      - `scale` number: Scale of the hidden state; 1 is its resting size.
      - `text` OverlayAnimationTextInput: On `textIntro`/`textOutro` only: which units play the side, each in turn. Required on a new text side.
        - `delayMs` number: How long after one unit the next starts, in ms (0 to 2000). Defaults to 100.
        - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random': Which unit goes first. `random` uses the same shuffle every time. Defaults to `forward`.
        - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing': Eases the delays across the units. Defaults to `linear`.
        - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
  - `background` TextOverlayBackground: Background behind a text overlay, in the same object shape as a clip background.
    - `color` string, required: Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
    - `type` 'solid', required: Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text.
  - `backgroundPadding` number: 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.
  - `color` string: 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.
  - `depthChanges` object[]: Changes of `depth` over the overlay's own time, each held until the next: `atMs` after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind them (a ring orbiting their head, a title they step in front of). `depth` is where it starts. On updates, omit it to leave the changes as they are; `[]` removes them. Absent in responses while the overlay holds one depth.
    - `atMs` number, required: Ms after the overlay starts.
    - `depth` 'front' | 'behind_presenter', required: 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.
  - `dimensions` OverlayDimensions: 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.
    - `height` number, required
    - `width` number, required
  - `durationMs` integer
  - `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.
  - `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`.
  - `fontSize` number: Font size in artboard pixels.
  - `fontWeight` number
  - `fontWidth` number
  - `letterSpacing` number: 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.
  - `outline` string, nullable: Color of the outline (stroke) drawn around the letters, or null for no outline.
  - `point` OverlayPoint: Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes.
    - `xPct` number, required
    - `yPct` number, required
  - `presetId` string: 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.
  - `startTimeMs` integer: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
  - `text` string
  - `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.
  - `zIndex` integer: 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.

## Response `200`

OK

- ClipTextOverlayResponse: A text overlay on a clip
  - `textOverlay` ClipTextOverlay, 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.
    - `animation` OverlayAnimation, required: How the overlay enters and leaves, like the editor's Animate panel. When set it replaces `transition`.
      - `intro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `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.
        - `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.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `motionBlur` boolean, required: Blur the overlay along its motion while it moves, scales or turns.
      - `outro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `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.
        - `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.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `textIntro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `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.
        - `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.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `textOutro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', 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`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `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.
        - `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.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
    - `background` TextOverlayBackgroundOutput, required: Background behind a text overlay, in the same object shape as a clip background.
      - `color` string, required: Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
      - `type` 'solid', required: Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text.
    - `backgroundPadding` number, required: 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', required: Shape of the solid background behind the text.
    - `color` string, required: Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
    - `depth` 'front' | 'behind_presenter', required: 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.
    - `depthChanges` object[]: Changes of `depth` over the overlay's own time, each held until the next: `atMs` after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind them (a ring orbiting their head, a title they step in front of). `depth` is where it starts. On updates, omit it to leave the changes as they are; `[]` removes them. Absent in responses while the overlay holds one depth.
      - `atMs` number, required: Ms after the overlay starts.
      - `depth` 'front' | 'behind_presenter', required: 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.
    - `dimensions` OverlayDimensionsOutput, required: 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.
      - `height` number, required
      - `width` number, required
    - `durationMs` number, required
    - `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`.
    - `fontId` string: The library font the overlay renders with (a `font` item's id), absent for a catalog family.
    - `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.
    - `fontWeight` number, required: Variable-font weight axis — 100 (thin) to 900 (black).
    - `fontWidth` number, required: Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded.
    - `id` string, required: Text overlay ID
    - `letterSpacing` number, required: 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.
    - `outline` string, nullable, required: Color of the outline (stroke) drawn around the letters, or null for no outline.
    - `point` OverlayPointOutput, 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.
      - `xPct` number, required
      - `yPct` number, required
    - `shadow` 'none' | 'subtle' | 'deep', required: Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters.
    - `startTimeMs` number, required: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
    - `text` string, required
    - `textAlign` 'left' | 'center' | 'right', required: Horizontal alignment of the text inside its overlay box.
    - `transition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
    - `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.

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: 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.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 72 revisions in range; 1 not diffed.

- **2026-11-07** `0cc3fcd307ad`: 2 info
  - added the new optional request property `letterSpacing`
  - added the required property `textOverlay/letterSpacing` to the response with the `200` status
- **2026-10-30** `0b2b8234a7db`: 2 info
  - added the new optional request property `backgroundPadding`
  - added the required property `textOverlay/backgroundPadding` to the response with the `200` status
- **2026-10-22** `156b28c30e54`: 2 info
  - added the new optional request property `depthChanges`
  - added the optional property `textOverlay/depthChanges` to the response with the `200` status
- **2026-10-09** `9773130bbc2b`: 2 info
  - added the new optional request property `animation`
  - added the required property `textOverlay/animation` to the response with the `200` status
- **2026-10-08** `574947531a33`: 2 info
  - added the new optional request property `fontId`
  - added the optional property `textOverlay/fontId` to the response with the `200` status

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/text-overlays/:textOverlayId/patch.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/ca74daaf9201?raw)