WIwithchima
Clips

Add an overlay to a clip

Changed on

Adds an image or video overlay to a clip. Upload the bytes via POST /v1/sources (kind: image or kind: video) and pass the sourceId; the overlay type follows the source's kind.

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

Request

Path parameters

idstring required

Video identifier

Example:vid_abc123def456
clipIdstring required

Clip identifier

Example:cl_xyz789ghi012

Request body

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
motionDocumentIdstring

In place of sourceId: a Tella Motion document of this video's (ffd_…, from POST /v1/motion/documents), shown as the overlay. It is linked, not copied: it plays live, so edits to the document show in the video at once.

namestring
sourceIdstring

Source ID from POST /v1/sources (kind: image or kind: video). The overlay type follows the source's kind. Pass this or motionDocumentId.

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"
    }
  },
  "depth": "behind_presenter",
  "depthChanges": [
    {
      "atMs": 1200,
      "depth": "behind_presenter"
    }
  ],
  "dimensions": {
    "height": 540,
    "width": 960
  },
  "durationMs": 5000,
  "motionDocumentId": "ffd_abc123",
  "name": "Logo",
  "point": {
    "xPct": 30,
    "yPct": 30
  },
  "sourceId": "su_abc123",
  "startTimeMs": 1000,
  "transition": "smooth"
}

Response

OK

Example response

{
  "overlay": {
    "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"
        }
      }
    },
    "depth": "behind_presenter",
    "depthChanges": [
      {
        "atMs": 1200,
        "depth": "behind_presenter"
      }
    ],
    "dimensions": {
      "height": 540,
      "width": 960
    },
    "durationMs": 5000,
    "id": "ly_abc123",
    "motionDocumentId": "ffd_abc123",
    "name": "Logo",
    "point": {
      "xPct": 30,
      "yPct": 30
    },
    "sourceId": "su_abc123",
    "startTimeMs": 1000,
    "transition": "smooth",
    "type": "image"
  }
}

Changes

  • 5e88f2f4b81dRevision changes
    • info

      added the new optional request property

  • 156b28c30e54Revision changes
    • warning

      added the new motion enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property became optional

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status