--- title: "Update an overlay" method: PATCH path: "/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}" tags: ["Clips"] --- # Update an overlay `PATCH /v1/videos/{id}/clips/{clipId}/overlays/{overlayId}` ## Request - Base URL: `https://api.tella.com` - URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/overlays/{overlayId}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Update an overlay's name, timing, position, or dimensions. Only the fields you send are changed. ## Path parameters - `id` string, required: Video ID - `clipId` string, required: Clip ID - `overlayId` string, required: Overlay ID ## Request body - UpdateClipOverlayRequest: Update an existing 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. - `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 - `name` string - `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 - `startTimeMs` integer: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. - `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 - ClipOverlayResponse: An overlay on a clip - `overlay` ClipOverlay, required: An image, video or Tella Motion overlay on a clip. - `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. - `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 - `id` string, required: Overlay ID - `imageUrl` string, nullable: Hosted image URL, for image overlays. Read-only: not accepted as input — pass `sourceId` instead. - `motionDocumentId` string: The Tella Motion document (ffd_…) a `motion` overlay plays. Edit it with `POST /v1/motion/documents/{id}/commands`. - `name` string, nullable - `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 - `sourceId` string, nullable: Source ID the overlay was created from. - `startTimeMs` number, required: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. - `transition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly. - `type` 'image' | 'video' | 'motion', required: `motion` plays a Tella Motion document of the video's live (`motionDocumentId`). - `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-10-22** `156b28c30e54`: 1 warning, 3 info - added the new `motion` enum value to the `overlay/type` response property for the response status `200` - added the new optional request property `depthChanges` - added the optional property `overlay/depthChanges` to the response with the `200` status - added the optional property `overlay/motionDocumentId` to the response with the `200` status - **2026-10-09** `9773130bbc2b`: 2 info - added the new optional request property `animation` - added the required property `overlay/animation` to the response with the `200` status - **2026-09-29** `704d6fc3bc60`: 2 info - added the new optional request property `zIndex` - added the required property `overlay/zIndex` to the response with the `200` status - **2026-09-28** `ac47c99c144f`: 9 warning - added the new `edit_conflict` enum value to the `error` response property for the response status `400` - added the new `edit_conflict` enum value to the `error` response property for the response status `401` - added the new `edit_conflict` enum value to the `error` response property for the response status `403` - added the new `edit_conflict` enum value to the `error` response property for the response status `404` - …5 more - …earlier changes not shown [Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/overlays/:overlayId/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)