Introduction
What this endpoint does
It separates the main subject of a video from everything behind it, with no green screen and no selection step. Hair, fur and loose fabric keep soft edges.
Inputs that matter
video_url takes one clip of at most 120 seconds. output_format decides the result: mp4, webm or matte. With mp4 you can add background_image_url or background_video_url. resolution is 480p or 720p.
What you get back
One video at the source aspect ratio and length, with the original sound.
| Field | Value |
|---|---|
| Input | Video |
| Output | Video |
| Endpoint | Video edit |
| Backgrounds | Your image or video (mp4 only); white when none |
| Outputs | MP4, transparent WebM (VP9 alpha) or black-and-white matte MP4 |
| Resolution | 480p or 720p, source aspect ratio kept |
| Billing | Source seconds × the rate of the chosen resolution; 3 s minimum |
Key features & highlights
From a seaside terrace to a city rooftop
We took a 5-second clip of a woman on a terrace above the sea and sent a rooftop sunset video as the background. She came back on the rooftop with her long hair still in loose strands, the backdrop moving behind her and the clip's sound intact. A still image works the same way; with no background at all, the MP4 comes back on white.
A black-and-white matte for your own compositing
The matte output is an MP4 in which white is the subject and black is everything else, at the same length and frame rate as the source. Pair it with the original clip in an editor that takes a luma key.
WebM with a real alpha channel
Pick webm for a VP9 file whose background is transparent, ready to drop over gameplay, slides or another shot. Chrome, Edge and Firefox show the transparency; Safari plays the same file on black.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | The clip to process: an MP4 or WebM upload or a direct file link, at most 120 seconds. A clip over that limit is rejected before processing, at no charge. at least 1 characters |
output_format | No | mp4 (default) returns the subject on your background image or video, or on white. webm returns VP9 with transparency (Safari shows it on black). |
background_image_url | No | Optional JPEG, PNG or WebP placed behind the subject and scaled to fill the frame. Only with |
background_video_url | No | Optional MP4 or WebM placed behind the subject, scaled to fill the frame and looped when shorter than the clip. at least 1 characters |
resolution | No | Output size: 480p or 720p (default). The source aspect ratio is kept. |
Pricing
Billed per second of the source clip at the selected resolution, rounded up to the whole second, with a 3-second minimum. A clip over 120 seconds is turned away when submitted. Output format and background do not change the price. Failed requests are not charged.
| Specification | Price |
|---|---|
| $0.024 / second |
| $0.048 / second |
Use cases
Talking heads on a branded set
Put a presenter recorded in an ordinary room in front of a studio still or a looping motion background, without a green screen or reshoot.
Overlays for edits and streams
A transparent WebM of a dancer, a pet or a product can sit over gameplay, slides or another shot in any editor that reads VP9 alpha.
Key tracks for compositing
The matte output gives a clean black-and-white track to pair with the original clip in After Effects, DaVinci Resolve or Nuke-style pipelines.
Prompt guide & pro tips
Upload a clip with one clear subject
Detection is automatic: there is no prompt and no click selection. A single person or object in front of the camera gives the cleanest cut. Clips can run up to 120 seconds.
Choose what you want back
mp4 for a finished shot on a new background, webm when you need transparency, matte when your editor expects a key track. The background image or video is used only with mp4.
Preview at 480p, deliver at 720p
Both sizes keep the source aspect ratio. 720p costs twice the per-second rate of 480p, so check the cut on a short 480p pass first.
Introduction
Video Background Remover Pro takes an ordinary clip, finds the person or object in front of the camera and separates it from the scene. You decide what comes back: the subject on a new background, the subject alone on transparency, or a black-and-white matte to key with in your own editor.
Request
{
"video_url": "https://example.com/beach.mp4",
"background_video_url": "https://example.com/city-lights.mp4",
"output_format": "mp4",
"resolution": "720p"
}
Only video_url is required. output_format defaults to mp4 and resolution to 720p. Send at most one of background_image_url and background_video_url, and only with mp4; without either, the subject is placed on white.
The three outputs
mp4: a finished shot. A background image is scaled to fill the frame; a background video is scaled the same way and loops if it is shorter than your clip.webm: VP9 with an alpha channel. Chrome, Edge and Firefox show it as transparent; Safari plays it on black.matte: an MP4 in which white is the subject and black is everything else, aligned frame for frame with your source.
What we saw in testing
We ran a 3-second 16:9 beach clip of a woman with wind-blown hair against a low sun. At 480p each output came back as 854×480 at 24 fps, and at 720p as 1280×720; processing took about one to two minutes per clip. A wider 2:1 terrace clip came back at 906×452 and 25 fps: the size follows the pixel count of the chosen setting rather than a fixed height, and the source frame rate is kept. Fine strands of hair stayed separate in the matte, the WebM decoded with a real alpha channel, and the MP4 versions kept the original audio. A 2-second clip was billed as 3 seconds, the minimum.
Task flow
The call is asynchronous: create the task, poll until it finishes, then download the video from SpicyAPI storage. Failed requests are not charged.
Tips
- Trim the clip to the part you need before uploading; billing follows the source length.
- One clear subject works best. With several people in frame, the tool decides which one is the subject.
- For transparency in a browser that has to include Safari, use the matte together with the original clip instead of the WebM.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/background-remover-video-pro/video-edit",
"input": {
"output_format": "mp4",
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.



