Video Background Removal API

Integrate the most powerful video background removal AI into your app or workflow with ease.

Get started

Get your API key
Use the sample code below to get started quickly
Review the reference docs to adjust any parameters

Overview

Submit a video:
Call POST /videos with your video URL or file.
Fetch the video status:
Call GET /videos/:id to fetch the status of your video.
(Alternatively, register a webhook_url to receive a callback when the processing is finished.)
Download the result:
When the status is done, download the result from the result_url.
If required, continue with further processing of the result.

Note: The Unscreen API is currently in beta status and might still change. Please share your feedback and questions!

Authentication

Each request must include an X-Api-Key header with your API key.

POST /v1.0/videos Host: api.unscreen.com X-Api-Key: <YOUR-API-KEY>

Output formats and backgrounds

You can choose between the following formats through the format parameter:

Pro Bundle (pro_bundle)
A ZIP archive containing the following files: alpha.mp4 (alpha matte video) and color.mp4 (color video). The Pro Bundle offers the highest quality and is recommended as an intermediate format. To convert it into a final video file, additional processing is required.
MP4 video (mp4)
An MP4 video file. The use of this format requires setting a background_color because MP4 videos do not support transparency.
Animated GIF (gif)
An animated GIF file. This format is only available for videos up to 20 seconds. The output is limited to a resolution of 720p (1280x720), a frame rate of 30 fps, and provides a lower quality than other formats due to compression. The color palette is limited and edges may appear pixelated if no background_color is set.

Working with the Pro Bundle file

There is currently no widely supported video format that supports transparency for high-quality video content. While there are several promising candidates for the future, the Pro Bundle format is our solution to combine an alpha matte with a high quality video and a reasonable file size.

Pro Bundle is a regular ZIP archive, containing two files:

alpha.mp4 An alpha matte video in MP4 format.
color.mp4 An color video in MP4 format. Note that this video is similar to the input video, however some colors are adjusted to remove background color spill.

Pro Bundle is an intermediate format and can not be played in a video player. In order to use it, it needs further processing;

Unpack the ZIP archive
Apply the alpha matte to the color video
Save the result in a format that supports transparency (such as WEBM)
OR
Add a new background and then save the result (for instance as MP4)

These steps can be automated with tools and libraries such as FFmpeg and unzip (see sample code). Alternatively, you can also perform them manually.

Sample Code

The following sample codes rely on CLI tools. For a full integration example, take a look at our demo app source code.

Submit a video from a URL

curl -X POST "https://api.unscreen.com/v1.0/videos" \
     -H "X-Api-Key: <YOUR-API-KEY>" \
     -F "video_url=https://media.giphy.com/media/yJFeycRK2DB4c/giphy.gif"

Submit a video from a file

curl -X POST "https://api.unscreen.com/v1.0/videos" \
     -H  "X-Api-Key: <YOUR-API-KEY>" \
     -F "video_file=@/path/to/file.mp4"

Get list of all videos

curl "https://api.unscreen.com/v1.0/videos" \
     -H "X-Api-Key: <YOUR-API-KEY>"

Get a single video

curl "https://api.unscreen.com/v1.0/videos/<VIDEO-ID>" \
     -H "X-Api-Key: <YOUR-API-KEY>"

Unpack a Pro Bundle

unzip unscreen-result.zip

Convert unpacked Pro Bundle to WEBM video with transparency

ffmpeg -i color.mp4 -i alpha.mp4 \
       -filter_complex [0][1]alphamerge,format=yuva420p \
       -c:v libvpx -strict -2 -auto-alt-ref 0 \
       output.webm

Convert unpacked Pro Bundle to animated GIF with transparency

ffmpeg -i color.mp4 -i alpha.mp4 \
       -filter_complex "[0][1]alphamerge[coloralpha];[coloralpha]split[coloralpha1][coloralpha2];[coloralpha1]palettegen=reserve_transparent=on:transparency_color=ffffff[palette];[coloralpha2][palette]paletteuse[output]" \
       -map [output] output.gif

Convert unpacked Pro Bundle to MP4 with background video

ffmpeg -stream_loop -1 -i background.mp4 -i color.mp4 -i alpha.mp4 \
       -filter_complex "[1][2]alphamerge[coloralpha];[0][coloralpha]scale2ref='main_w*max(iw/main_w, ih/main_h)':'main_h*max(iw/main_w, ih/main_h)'[background][coloralpha];[background][coloralpha]overlay=shortest=1:x=main_w/2-overlay_w/2:y=main_h-overlay_h[merged];[merged]setdar=dar=a[darset];[darset]pad=ceil(iw/2)*2:ceil(ih/2)*2[output]" \
       -crf:v 17 -pix_fmt yuv420p -strict -2 -c:v libx264 -c:a copy \
       -map [output] -map 1:a output.mp4

Convert unpacked Pro Bundle to MP4 with background color

ffmpeg -stream_loop -1 -f lavfi -i "color=color=#00ff00" -i color.mp4 -i alpha.mp4 \
       -filter_complex "[1][2]alphamerge[coloralpha];[0][coloralpha]scale2ref='main_w*max(iw/main_w, ih/main_h)':'main_h*max(iw/main_w, ih/main_h)'[background][coloralpha];[background][coloralpha]overlay=shortest=1:x=main_w/2-overlay_w/2:y=main_h-overlay_h[merged];[merged]setdar=dar=a[darset];[darset]pad=ceil(iw/2)*2:ceil(ih/2)*2[output]" \
       -crf:v 17 -pix_fmt yuv420p -strict -2 -c:v libx264 -c:a copy \
       -map [output] -map 1:a output.mp4

Webhooks

Instead of fetching status updates from GET /videos/{id} a webhook can be registered when submitting a video through the webhook_url parameter.

The webhook will be called through an HTTP POST request once the processing is finished (either with status done or error). You can use this webhook to trigger further processing of the video on your end.

The payload of the POST request contains the event type (video:done or video:error) and the video data.

Example payload

 {
  "type": "video:done",
  "data": {
    "type": "video",
    "id": "792e37c4-42ad-4ab9-9cde-228864572ce8",
    "attributes": {
      "status": "done",
      "result_url": "https://v.unscreen.com/792e37c4-42ad-4ab9-9cde-228864572ce8/result.mp4",
    },
    "links": {
      "self": "https://api.unscreen.com/v1.0/videos/792e37c4-42ad-4ab9-9cde-228864572ce8"
    }
  }
}

Pricing

API requests come at no extra charge. To process videos, an Unscreen Pro subscription is required.

Videos are charged from your account balance depending on their length. The minimum video length is 1 second. Fractions of a second are rounded up. Videos with frame rates above 30 fps are charged at a multiple of their length.

Rate limits

In order to provide a reliable service for all our users, the following rate limits are enforced:

Clients can perform up to 90 API requests per minute.
Clients can create up to 10 videos per minute.
After 10 failed processing attempts in one hour, no more videos can be submitted until the next hour.

If you require a higher rate limit, please contact us.

Data Retention

Videos are stored for 30 days. If you wish, you can delete them earlier through DELETE /videos/{id}.

Deleted videos can not be restored, so make sure to download the results before it's too late.

Reference

Please view this page on on a larger device to see the full API Reference.

Get help

If you have questions or feedback, contact us. We're happy to help!