curl -X POST "https://api.hooked.so/v1/image/remove-background" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "imageUrl": "https://example.com/portrait.jpg" }'
const response = await fetch('https://api.hooked.so/v1/image/remove-background', {
method: 'POST',
headers: { 'x-api-key': 'your_api_key_here', 'Content-Type': 'application/json' },
body: JSON.stringify({ media: 'media_abc123' })
});
const { data } = await response.json();
console.log(data.backgroundRemovedUrl); // PNG with transparency
import requests
response = requests.post(
'https://api.hooked.so/v1/image/remove-background',
headers={'x-api-key': 'your_api_key_here'},
json={'imageUrl': 'https://example.com/portrait.jpg'}
)
print(response.json()['data']['backgroundRemovedUrl'])
{
"success": true,
"message": "Background removal started",
"data": {
"mediaId": "media_abc123",
"status": "PROCESSING",
"url": "https://.../portrait.jpg",
"jobId": "aab23fd5fe10445c8fc1d2821b1482bd",
"usedCredits": 0.5
}
}
{
"success": true,
"message": "Background already removed",
"data": {
"mediaId": "media_abc123",
"status": "COMPLETED",
"url": "https://.../portrait.jpg",
"backgroundRemovedUrl": "https://.../media_abc123-1726560000000.png",
"usedCredits": 0
}
}
Images
Remove Image Background
Cut the subject out of an image and get a PNG with a transparent background
POST
/
v1
/
image
/
remove-background
curl -X POST "https://api.hooked.so/v1/image/remove-background" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "imageUrl": "https://example.com/portrait.jpg" }'
const response = await fetch('https://api.hooked.so/v1/image/remove-background', {
method: 'POST',
headers: { 'x-api-key': 'your_api_key_here', 'Content-Type': 'application/json' },
body: JSON.stringify({ media: 'media_abc123' })
});
const { data } = await response.json();
console.log(data.backgroundRemovedUrl); // PNG with transparency
import requests
response = requests.post(
'https://api.hooked.so/v1/image/remove-background',
headers={'x-api-key': 'your_api_key_here'},
json={'imageUrl': 'https://example.com/portrait.jpg'}
)
print(response.json()['data']['backgroundRemovedUrl'])
{
"success": true,
"message": "Background removal started",
"data": {
"mediaId": "media_abc123",
"status": "PROCESSING",
"url": "https://.../portrait.jpg",
"jobId": "aab23fd5fe10445c8fc1d2821b1482bd",
"usedCredits": 0.5
}
}
{
"success": true,
"message": "Background already removed",
"data": {
"mediaId": "media_abc123",
"status": "COMPLETED",
"url": "https://.../portrait.jpg",
"backgroundRemovedUrl": "https://.../media_abc123-1726560000000.png",
"usedCredits": 0
}
}
Overview
Starts removing the background of an image; the result is a PNG with real transparency, attached to the image in your library a moment later. The call answers202 with the media to follow: poll Get Image until backgroundRemoval.status is COMPLETED.
The image can be one already in your library (media) or any public URL (imageUrl); a URL is imported into your library first, so the result is always attached to a media you own. An image that already has its background removed answers 200 at once, without a new charge; one whose removal is already running answers 202 again with the same job.
Accepted formats: JPEG, PNG and WEBP, up to 25 MB.
Request Body
string
ID of an image in your media library. Required unless
imageUrl is given.string
Public URL of the image to process. It is saved to your library before processing. Required unless
media is given.curl -X POST "https://api.hooked.so/v1/image/remove-background" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "imageUrl": "https://example.com/portrait.jpg" }'
const response = await fetch('https://api.hooked.so/v1/image/remove-background', {
method: 'POST',
headers: { 'x-api-key': 'your_api_key_here', 'Content-Type': 'application/json' },
body: JSON.stringify({ media: 'media_abc123' })
});
const { data } = await response.json();
console.log(data.backgroundRemovedUrl); // PNG with transparency
import requests
response = requests.post(
'https://api.hooked.so/v1/image/remove-background',
headers={'x-api-key': 'your_api_key_here'},
json={'imageUrl': 'https://example.com/portrait.jpg'}
)
print(response.json()['data']['backgroundRemovedUrl'])
{
"success": true,
"message": "Background removal started",
"data": {
"mediaId": "media_abc123",
"status": "PROCESSING",
"url": "https://.../portrait.jpg",
"jobId": "aab23fd5fe10445c8fc1d2821b1482bd",
"usedCredits": 0.5
}
}
{
"success": true,
"message": "Background already removed",
"data": {
"mediaId": "media_abc123",
"status": "COMPLETED",
"url": "https://.../portrait.jpg",
"backgroundRemovedUrl": "https://.../media_abc123-1726560000000.png",
"usedCredits": 0
}
}
Response Fields
string
The library image the cut-out belongs to (the imported one when
imageUrl was used).string
PROCESSING while Bria works (202), COMPLETED when the cut-out already existed (200).string
Signed URL of the original image.
string
The removal job, while it runs.
string
Signed URL of the PNG with the background removed, when
status is COMPLETED. Otherwise read it from Get Image once backgroundRemoval.status is COMPLETED.number
Credits charged by this call.
0 when nothing new was started.Status Codes
| Status | Code | Description |
|---|---|---|
| Started | 202 | Removal running; follow it with Get Image |
| Already done | 200 | The image already had its cut-out |
| Validation error | 400 | Missing or invalid media / imageUrl |
| Unauthorized | 401 | Missing or invalid API key |
| Payment required | 402 | Not enough credits, no active plan, or (BYOK) the Bria key is missing |
| Provider error | 502 | Bria did not take the request; nothing was charged |
backgroundRemoval.status: "FAILED" in Get Image and the credits are refunded.
Related Endpoints
Get Image
Follow the removal and read the result
Expand Image
Grow an image to another aspect ratio
Remove Video Background
The same for a video
Authorizations
Body
application/json