Introduction
Video Eraser removes content inside a static image mask across an entire video clip. Send video_url and mask_url, with an optional short prompt describing the removal. It is suited to a fixed subtitle band or another unwanted element that stays in the same screen region. The resulting background is an inferred fill, not a recovery of hidden original pixels.
Key features & highlights
A fixed region for the whole clip
The mask is a still image: white marks the area to erase, and black marks the area to retain. The same screen region applies throughout the supplied video. There is no start-time field, end-time field or moving-object tracking control. A subtitle that moves outside the white region will not be covered by that mask. Content passing through the selected region may also be altered by the fill.
An optional description alongside the mask
A brief description can clarify what should be removed and what surrounds it. The mask remains required on this endpoint so that the region is explicit. Processing is billed by the complete input clip, rounded up to whole seconds with a minimum billed duration of 3 seconds. Accepted source clips are 1 to 600 seconds long. A smaller mask does not reduce the billed video duration.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | The complete video to process, from 1 to 600 seconds. The selected region is processed for the full clip. at least 1 characters |
mask_url | Yes | One static PNG image aligned to the video frame. Paint the removal area white and the remaining area black. at least 1 characters |
prompt | No | Optional guidance for the local removal. It does not select a time interval or enable tracking. |
Pricing
$0.024 / second
Billed by the entire input clip, rounded up to whole seconds with a 3-second minimum charge. This endpoint accepts clips from 1 to 600 seconds; mask size does not reduce duration.
Use cases
Remove a fixed subtitle band
For captions already burned into your own footage, mark the subtitle band and inspect every section where text appears. A static background is a useful starting point for checking the result. If captions are still editable text layers in the project, remove those layers directly before choosing pixel reconstruction.
Clean a stationary overlay
Use a tight mask for an unwanted corner overlay in footage you are editing. Check frames where a person, product or moving camera passes behind the selected area. Those moments require the fill to infer changing content and can expose flicker or distorted edges that are not obvious in a single preview frame.
Prompt guide & pro tips
Make an unambiguous mask
Prepare a PNG mask aligned to the source frame: white inside the removal region, black outside it. Check placement against the first, middle and last frames before submitting. Avoid unnecessarily large white regions, especially when they overlap a face or an important product detail. The mask is static and affects the full clip; it cannot follow moving subtitles or limit the edit to a selected time interval.
Describe the local edit and compare the result
An optional instruction such as “Remove the fixed subtitle band and fill it with the surrounding background” describes the intended change without inventing a new scene. Compare the output with the original at normal playback speed and frame by frame around difficult motion. Check unmasked areas, clip length, frame rate and sound as well as the erased region. Original audio preservation and pixel-exact preservation outside the mask have not been verified, so keep the source file.
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/video-eraser-v1/video-edit",
"input": {
"mask_url": "https://example.com/reference.png",
"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.