BAbannerbear

Overlay video

Changed on

Layer one video on top of another as picture-in-picture. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed.

post/tools/overlay_video

Request

  • Base URL
    https://api.bannerbear.com/v5
  • Auth
    HTTP bearer

Request body

base_video_urlstring uri required

Base video URL

overlay_video_urlstring uri required

Overlay video URL

position'top_left' | 'top_center' | 'top_right' | 'center' | 'bottom_left' | 'bottom_center' | 'bottom_right'

Snap to a corner or edge. Use this or x/y, not both

margininteger

Gap from the edge when using position. Defaults to 0

xinteger

Absolute position from the left. Ignored when position is set

yinteger

Absolute position from the top. Ignored when position is set

scalenumber

1.0 = original size. Use this or width, not both

widthinteger

Exact size — the height follows the overlay's own proportions. For a circle this is the bubble's diameter

shape'rectangle' | 'circle'

Circle crops the overlay to a centred bubble

border_widthinteger

0 for no border

border_colorstring

Border color

shadow'off' | 'on'

Drop shadow

audio'base' | 'overlay' | 'mix'

Overlay and mixed audio need the overlay to have a soundtrack

startnumber

When the overlay begins

when_finished'freeze' | 'hide' | 'loop'

When the overlay ends

metadatastring

Arbitrary metadata string stored with the tool run

Response

Tool run accepted

uidstring
tool'overlay_video'
status'pending' | 'running' | 'completed' | 'failed'

pending → running → completed / failed

progressinteger

0-100 job progress, 100 once completed

inputsobject

Inputs the job was created with

metadatastring nullable

Arbitrary metadata string round-tripped from the create request

selfstring uri
created_atstring date-time
completed_atstring date-time nullable
error_messagestring nullable

Human-readable failure reason (only present on failed jobs)

Changes

  • 708a5945d283Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

  • c439420dbe16Revision changes
    • info

      added the new optional request property