Skip to navigation

Generate an alpha matte from a video

Separate the foreground of a video from its background. On completion, the result contains matte_video_url and cutout_video_url, described in Output.

Responds immediately with the job id and created_at timestamp. Poll GET /v2/video-alpha-gen/{id} until the status is completed.

Requests that violate the content policy fail the job with content_filtered_error. An account without enough credit fails the same way, with insufficient_funds_error.

Billed per second of input video. See Pricing.

Output

  • matte_video_url: a grayscale alpha matte MP4. White is foreground, black is transparent, and shades of gray are partly transparent.
  • cutout_video_url: the input video with the matte as its alpha channel, as a ProRes 4444 .mov with straight (not premultiplied) alpha, ready to composite. The cutout is encoded at 10 bits per channel, but carries 8-bit precision: its color is your input decoded to 8 bits and its alpha is the 8-bit matte. ProRes files are large: roughly 42 MB per second of video at 1080p and 172 MB per second at 4K.

Both files have the same frames as the input, one for one. They have the input’s resolution (an odd width or height is rounded down to an even number) and the input’s frame rate, rounded to a whole number. They have no audio.

Authentication

AuthorizationBearer
API key authentication

Request

This endpoint expects an object.
video_uristringRequired

Input video in HTTPS URL or base64 data URI format. See Input Formats for supported formats and codecs.

Max 200 MB (data URIs have a lower limit). The long side can be up to 3840 pixels and the short side up to 2160 pixels, so 4K video is accepted in landscape (3840×2160) or portrait (2160×3840). The long side can be at most 32:9 times the short side (e.g. 3840×1080). The frame rate must be at least 1 fps.

The maximum length depends on the short side (the smaller of width and height): up to 1080 pixels, 3,072 frames (about 2 minutes at 24fps, or about 1 minute 42 seconds at 30fps); up to 1440 pixels, 2,800 frames (about 1 minute 56 seconds at 24fps, or about 1 minute 33 seconds at 30fps); above 1440 pixels, such as 4K, 720 frames (30 seconds at 24fps, or 24 seconds at 30fps).

Response

Job submitted successfully
idstring
Unique job identifier. Use this to poll for status.
created_atdatetime
ISO 8601 timestamp of when the job was created.

Errors

400
Bad Request Error
401
Unauthorized Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error