WIwithchima
Clips

Update a shape overlay

Changed on

Update a shape overlay's outline, fill, corners, border, shadow, timing, position, size, animation, depth or stacking order. Only the fields you send are changed.

patch/v1/videos/{id}/clips/{clipId}/shape-overlays/{shapeOverlayId}

Request

Path parameters

idstring required

Video ID

clipIdstring required

Clip ID

shapeOverlayIdstring required

Shape overlay ID

Request body

corners'none' | 'regular' | 'squircle'

Shape of the solid background behind the text.

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
pathstring

A custom outline as SVG path data (d) in a 0–100 box; it stretches with the overlay box. Sending it makes the shape a path. Closed subpaths (ending in Z) are filled; an open path shows only its border, drawn centred on the line.

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.

shapeType'square' | 'circle' | 'triangle' | 'diamond' | 'star' | 'hexagon' | 'arrow' | 'path'

The outline, stretched to fill the overlay box: a non-square box makes a rectangle or an oval. path draws the overlay's own path.

startTimeMsinteger

Start time. Milliseconds on the clip playback timeline (with cuts applied).

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"
    }
  },
  "border": {
    "color": "#FFFFFFFF"
  },
  "corners": "squircle",
  "depth": "behind_presenter",
  "depthChanges": [
    {
      "atMs": 1200,
      "depth": "behind_presenter"
    }
  ],
  "dimensions": {
    "height": 540,
    "width": 960
  },
  "fill": {
    "color": "#000000ff",
    "gradientAngle": 45,
    "gradientColor1": "#ff0080ff",
    "gradientColor2": "#7928caff",
    "shaderGradientPreset": "Halo",
    "sourceId": "su_abc123",
    "type": "solid",
    "videoDurationSeconds": 12.4
  },
  "path": "M50 0 L100 100 L0 100 Z",
  "point": {
    "xPct": 30,
    "yPct": 30
  },
  "shadow": "subtle",
  "transition": "smooth"
}

Response

OK

Example response

{
  "shapeOverlay": {
    "border": {
      "color": "#FFFFFFFF"
    },
    "corners": "squircle",
    "depth": "behind_presenter",
    "depthChanges": [
      {
        "atMs": 1200,
        "depth": "behind_presenter"
      }
    ],
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "fill": {
      "color": "#000000ff",
      "gradientAngle": 45,
      "gradientColor1": "#ff0080ff",
      "gradientColor2": "#7928caff",
      "shaderGradientPreset": "Halo",
      "sourceId": "su_abc123",
      "type": "solid",
      "videoDurationSeconds": 12.4
    },
    "id": "ly_abc123",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "shadow": "subtle",
    "transition": "smooth"
  }
}

Changes