curl --request POST \
--url https://api.videobgremover.com/v1/jobs/{id}/refine-mask \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"op": "add",
"model": "videobgremover-pro",
"prompt": {
"mode": "text",
"text": "the left hand"
},
"edge_cleanup": {
"enabled": true,
"size": 512
}
}
'const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
op: 'add',
model: 'videobgremover-pro',
prompt: {mode: 'text', text: 'the left hand'},
edge_cleanup: {enabled: true, size: 512}
})
};
fetch('https://api.videobgremover.com/v1/jobs/{id}/refine-mask', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.videobgremover.com/v1/jobs/{id}/refine-mask"
payload = {
"op": "add",
"model": "videobgremover-pro",
"prompt": {
"mode": "text",
"text": "the left hand"
},
"edge_cleanup": {
"enabled": True,
"size": 512
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"refinement_id": "7b1c3f2e-9a4d-4c1b-8e2f-0a1b2c3d4e5f",
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"op": "add",
"model": "sam3",
"version": 2,
"credits_used": 30,
"created_at": "2026-06-28T12:00:00.000Z"
}Refine a job's mask with a SAM3 text prompt
Stack a second SAM3 text-prompt segmentation onto a completed job’s existing mask. Use this when background removal is mostly correct but misses (or over-includes) part of the subject.
op: "add"unions the new mask onto the existing one (fills a missing region).op: "subtract"removes the new mask’s region from the existing one.
The refinement is non-destructive: the original mask is preserved and a new
versioned mask is written. On completion the job’s active mask is updated, so a
subsequent re-export (POST /v1/jobs/{id}/exports) returns the refined result in
any format. Refinement runs GPU inference and consumes credits (refunded on failure).
Only one refinement may run per job at a time, and the job must be completed.
Send an optional Idempotency-Key to retry safely. The same key and request
return the original refinement and its current status without another charge.
Reusing a key with different inputs returns 409. Keys are scoped to your account
and job and retained with the refinement record. After a terminal failure, use a
new key for a new attempt. Version numbers may have gaps after failed attempts.
curl --request POST \
--url https://api.videobgremover.com/v1/jobs/{id}/refine-mask \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"op": "add",
"model": "videobgremover-pro",
"prompt": {
"mode": "text",
"text": "the left hand"
},
"edge_cleanup": {
"enabled": true,
"size": 512
}
}
'const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
op: 'add',
model: 'videobgremover-pro',
prompt: {mode: 'text', text: 'the left hand'},
edge_cleanup: {enabled: true, size: 512}
})
};
fetch('https://api.videobgremover.com/v1/jobs/{id}/refine-mask', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.videobgremover.com/v1/jobs/{id}/refine-mask"
payload = {
"op": "add",
"model": "videobgremover-pro",
"prompt": {
"mode": "text",
"text": "the left hand"
},
"edge_cleanup": {
"enabled": True,
"size": 512
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"refinement_id": "7b1c3f2e-9a4d-4c1b-8e2f-0a1b2c3d4e5f",
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"op": "add",
"model": "sam3",
"version": 2,
"credits_used": 30,
"created_at": "2026-06-28T12:00:00.000Z"
}