> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Remove Image Background
> Cut the subject out of an image and get a PNG with a transparent background
## 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 answers `202` with the media to follow: poll [Get Image](/api-reference/image/details) 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
ID of an image in your media library. Required unless `imageUrl` is given.
Public URL of the image to process. It is saved to your library before processing. Required unless `media` is given.
```bash cURL theme={null}
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" }'
```
```javascript Node.js theme={null}
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
```
```python Python theme={null}
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'])
```
```json 202 Started theme={null}
{
"success": true,
"message": "Background removal started",
"data": {
"mediaId": "media_abc123",
"status": "PROCESSING",
"url": "https://.../portrait.jpg",
"jobId": "aab23fd5fe10445c8fc1d2821b1482bd",
"usedCredits": 0.5
}
}
```
```json 200 Already done theme={null}
{
"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
The library image the cut-out belongs to (the imported one when `imageUrl` was used).
`PROCESSING` while Bria works (202), `COMPLETED` when the cut-out already existed (200).
Signed URL of the original image.
The removal job, while it runs.
Signed URL of the PNG with the background removed, when `status` is `COMPLETED`. Otherwise read it from [Get Image](/api-reference/image/details) once `backgroundRemoval.status` is `COMPLETED`.
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 |
If Bria fails later, the job ends as `backgroundRemoval.status: "FAILED"` in Get Image and the credits are refunded.
## Related Endpoints
Follow the removal and read the result
Grow an image to another aspect ratio
The same for a video
## OpenAPI
````yaml POST /v1/image/remove-background
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Images
description: 'Image editing: background removal and expansion'
paths:
/v1/image/remove-background:
post:
tags:
- Images
summary: Remove Image Background
description: >-
Start removing the background of an image; the PNG with transparency
lands on the media a moment later. Answers 202 with the media to follow
through GET /v1/image/{mediaId}. 200 at once when the image already has
its cut-out (no new charge); 202 again when a removal is already
running.
operationId: removeImageBackground
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
media:
type: string
description: >-
ID of an image in your media library. Required unless
imageUrl is given.
imageUrl:
type: string
format: uri
description: >-
Public URL of a JPEG, PNG or WEBP image (up to 25 MB).
Imported into your library before processing. Required
unless media is given.
example:
imageUrl: https://example.com/portrait.jpg
responses:
'200':
description: The image already had its cut-out
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
mediaId:
type: string
status:
type: string
enum:
- COMPLETED
url:
type: string
backgroundRemovedUrl:
type: string
description: Signed URL of the PNG with transparency
usedCredits:
type: number
example:
success: true
message: Background already removed
data:
mediaId: media_abc123
status: COMPLETED
url: https://.../portrait.jpg
backgroundRemovedUrl: https://.../media_abc123-1726560000000.png
usedCredits: 0
'202':
description: Removal started (or already running)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
mediaId:
type: string
status:
type: string
enum:
- PROCESSING
url:
type: string
description: Signed URL of the original image
jobId:
type: string
usedCredits:
type: number
example:
success: true
message: Background removal started
data:
mediaId: media_abc123
status: PROCESSING
url: https://.../portrait.jpg
jobId: aab23fd5fe10445c8fc1d2821b1482bd
usedCredits: 0.5
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: media or imageUrl is required
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Not authenticated
'402':
description: >-
Payment required: not enough credits, no active plan, or (BYOK) the
Bria key is missing
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
errorCode:
type: string
enum:
- INSUFFICIENT_CREDITS
- SUBSCRIPTION_REQUIRED
- MISSING_CREDENTIALS
message:
type: string
missingProviders:
type: array
items:
type: string
creditsNeeded:
type: number
creditsAvailable:
type: number
example:
success: false
errorCode: INSUFFICIENT_CREDITS
message: Not enough credits to perform this action
creditsNeeded: 0.5
creditsAvailable: 0
'502':
description: Bria did not take the request; nothing was charged
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Bria could not process the image
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````