On this section
Video Background Removal Standard
Submit a video background removal job
Start an asynchronous job that removes the background from a source video, keeping only the foreground subject. Accepts source videos up to 4K.
Inputs
video_url— public URL of the source videooutput_codec— optional;vp9(the default) renders one WebM with an alpha channel,h264renders two files (the RGB video and an alpha matte) and is recommended for better RGB qualityrefine_foreground_edges— optional; improves the quality of the extracted subject's edges (defaults to true)subject_is_person— optional; set to false when the subject is not a person (defaults to true)
What happens next
The job is accepted immediately — you get 202 Accepted with a job_id and status PROCESSING. Rendering runs in the background; poll GET /v1/video-background-removal/{job_id} until the job is COMPLETED or FAILED.
Headers
X-Veed-Store-IOenumoptionalSet to 0 to not store this request's and response's bodies. They are then not available in your request logs for debugging.
01Defaults to "1".X-Veed-Media-Expiration-SecondsintegeroptionalNumber of seconds before the media URLs returned for this request expire. A value above the maximum is capped rather than rejected.
86400.Request body VideoBackgroundRemovalInput ↗
output_codecenumoptionalOutput encoding. vp9 (the default) yields a single webm video with an alpha channel; h264 yields two files (the RGB video and an alpha matte) and is recommended for better RGB quality.
vp9h264Defaults to "vp9".refine_foreground_edgesbooleanoptionalImproves the quality of the extracted subject's edges.
true.subject_is_personbooleanoptionalSet to false when the subject is not a person.
true.video_urlurlrequiredURL of the source video to remove the background from.
Responses
Show 6 nested fields
credits_chargedintegeroptionalCredits charged for the job. Present once the job is COMPLETED and the final charge is known.
credits_estimatedintegeroptionalCredits quoted before the job ran. Present only on the response that created the job. This is an estimate, not the price: the charged amount can be higher or lower.
Failure information. Present once the job has FAILED.
Show 3 nested fields
codeenumrequiredStable, machine-readable failure code for this job type.
input_validationcontent_moderationinvalid_fileaudio_too_longtransload_failedgeneration_failedtimeoutOptional structured failure details.
Show 3 nested fields
fieldstringoptionalDotted path to the offending input, when applicable.
messagestringrequiredHuman-readable explanation of this detail.
typestringrequiredThe category of this detail entry.
messagestringrequiredHuman-readable failure message.
job_iduuidrequiredStable identifier of the job and of the resource it produces.
The produced resource. Present once the job is COMPLETED.
Show 1 nested field
Rendered background-removed file(s): one webm with alpha for vp9; the RGB video and the alpha matte (two files) for h264.
Show 4 nested fields
content_typestringoptionalThe mime type of the file.
file_namestringoptionalThe name of the file.
file_sizeintegeroptionalThe size of the file in bytes.
urlstringrequiredThe URL where the file can be downloaded from.
statusenumrequiredCurrent lifecycle state of the job.
PROCESSINGCOMPLETEDFAILEDCANCELLEDX-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.401UnauthorizedErrorResponse ↗
Show 4 nested fields
codeenumrequiredinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternalShow 6 nested fields
fieldstringoptionalmessagestringoptionalreasonenumoptionalapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundoauth_token_invalidretry_after_msintegeroptionaltypestringrequiredvalueobjectoptionalmessagestringrequiredrequest_idstringrequiredX-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.402Payment RequiredErrorResponse ↗
Show 4 nested fields
codeenumrequiredinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternalShow 6 nested fields
fieldstringoptionalmessagestringoptionalreasonenumoptionalapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundoauth_token_invalidretry_after_msintegeroptionaltypestringrequiredvalueobjectoptionalmessagestringrequiredrequest_idstringrequiredX-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.422Unprocessable EntityErrorResponse ↗
Show 4 nested fields
codeenumrequiredinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternalShow 6 nested fields
fieldstringoptionalmessagestringoptionalreasonenumoptionalapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundoauth_token_invalidretry_after_msintegeroptionaltypestringrequiredvalueobjectoptionalmessagestringrequiredrequest_idstringrequiredX-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.429Rate limit exceededErrorResponse ↗
Show 4 nested fields
codeenumrequiredinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternalShow 6 nested fields
fieldstringoptionalmessagestringoptionalreasonenumoptionalapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundoauth_token_invalidretry_after_msintegeroptionaltypestringrequiredvalueobjectoptionalmessagestringrequiredrequest_idstringrequiredRetry-AfterSeconds until the rate limit resets.X-RateLimit-ClassThe rate-limit class that was hit (read, mutation, ai-generation).X-RateLimit-LimitRequest budget for the matched class.X-RateLimit-RemainingRemaining requests in the current window.X-RateLimit-ResetUnix time (seconds) when the budget resets.X-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.500Internal Server ErrorErrorResponse ↗
Show 4 nested fields
codeenumrequiredinvalid_requestunauthenticatedinsufficient_tokenspermission_deniednot_foundconflictrate_limitedunavailableinternalShow 6 nested fields
fieldstringoptionalmessagestringoptionalreasonenumoptionalapi_key_expiredapi_key_inactiveapi_key_invalidapi_key_revokedapi_key_workspace_unavailableinsufficient_creditsjob_not_foundoauth_token_invalidretry_after_msintegeroptionaltypestringrequiredvalueobjectoptionalmessagestringrequiredrequest_idstringrequiredX-Request-IDCorrelation id for this request, adopted from the request or minted at the edge.Example request
curl -X POST "https://api.veed.io/v1/video-background-removal" \
-H "Authorization: Bearer $VEED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://static-assets.veed.io/api-examples/bg-v2v-input.mp4"
}'import { Veed } from "@veedstudio/sdk";
const client = new Veed(); // reads VEED_API_KEY
const job = await client.videoBackgroundRemoval.submit({
video_url: "https://static-assets.veed.io/api-examples/bg-v2v-input.mp4",
});
console.log(job.status);package main
import (
"context"
"fmt"
"log"
veed "github.com/veedstudio/veed-sdk-go"
)
func main() {
client, err := veed.NewClient() // reads VEED_API_KEY
if err != nil {
log.Fatal(err)
}
job, err := client.VideoBackgroundRemoval.Submit(context.Background(), veed.VideoBackgroundRemovalInput{
VideoURL: "https://static-assets.veed.io/api-examples/bg-v2v-input.mp4",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(job.Status)
}Example response
{
"data": {
"credits_charged": 0,
"credits_estimated": 0,
"error": {
"code": "input_validation",
"details": [
{
"field": "<field>",
"message": "<message>",
"type": "<type>"
}
],
"message": "<message>"
},
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"files": [
{
"content_type": "video/mp4",
"file_name": "<file_name>",
"file_size": 0,
"url": "<url>"
}
]
},
"status": "PROCESSING"
}
}