WIwithchima
Clips

Add a shape overlay to a clip

Changed on

Adds a square, circle, triangle, diamond, star, hexagon or arrow on top of a clip, filled with any clip background and with an optional border and shadow.

post/v1/videos/{id}/clips/{clipId}/shape-overlays

Request

Path parameters

idstring required

Video identifier

Example:vid_abc123def456
clipIdstring required

Clip identifier

Example:cl_xyz789ghi012

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 required
namestring

Label in the editor's timeline.

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 required

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.

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
  },
  "durationMs": 5000,
  "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",
  "startTimeMs": 1000,
  "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