API#
Base URL: http://<host>:8000. OpenAPI: GET /openapi.json. Interactive Swagger UI at /docs; it is served by the container, so it works without internet.
No authentication. For AI coding assistants: GET /llms.txt (same as AGENTS.md).
Which endpoint:
| Client | Use |
|---|---|
| Server code with image bytes | POST /v1/remove-background: raw bytes or multipart in, PNG out |
| JSON-only client (browser, workflow tool, serverless) | POST /v1/remove-background/base64: base64 in, base64 out |
| Smart Brush editor | either; /base64 returns the matte to send back with the next edit |
| Method | Path | Purpose |
|---|---|---|
POST | /v1/remove-background | Remove the background, or fix a result with Smart Brush masks. Image bytes in, PNG out (or JSON, see below) |
POST | /v1/remove-background/base64 | Same, for JSON clients: base64 image in, base64 image out |
GET | /ready | 200 {"status":"ready"} once the model is loaded, 503 before |
GET | /health | Liveness: {"status":"ok","model":"withoutbg-pro-self-host","version":"10.12.4"} (the container's Docker HEALTHCHECK uses it) |
GET | /llms.txt | This API as plain text for AI coding assistants |
GET | /v1/licenses | License summary and upstream components (DINOv3, Depth Anything V2, BiRefNet). Full notices: /opt/withoutbg/v4/THIRD_PARTY_NOTICES.md in the image |
POST /v1/remove-background#
Query parameter:
| Name | Default | Meaning |
|---|---|---|
output | cutout | Binary responses only: cutout (transparent PNG) or matte (alpha as a black-and-white PNG) |
Images: JPEG, PNG, WebP and other formats Pillow reads, any size. EXIF orientation is applied. The result has the same size as the (oriented) input.
The request body can take three forms.
1. Raw bytes → PNG#
Shell
curl -H 'Content-Type: image/jpeg' --data-binary @photo.jpg \
'localhost:8000/v1/remove-background?output=cutout' -o cutout.png2. Multipart → PNG#
Field image (required), plus the optional Smart Brush fields below.
Shell
curl -F image=@photo.jpg -F keep_mask=@keep.png -F remove_mask=@remove.png \
localhost:8000/v1/remove-background -o fixed.png3. JSON → JSON#
Content-Type: application/json. Images are data URLs (data:image/png;base64,...)
or raw base64.
JSON
{
"image": "data:image/jpeg;base64,...",
"keep_mask": "data:image/png;base64,...",
"remove_mask": "data:image/png;base64,...",
"matte": "data:image/png;base64,..."
}Response:
JSON
{
"processed": "data:image/png;base64,...",
"alphaMatte": "data:image/png;base64,...",
"latencyMs": 812,
"routeCategory": "fine_strand",
"routePipeline": "matting"
}processed is the transparent cutout, alphaMatte the matte (black-and-white PNG). routeCategory
and routePipeline say which branch of the model handled the image; log them if you
report a result to us.
Binary responses carry the same information in headers: X-Latency-Ms,
X-Route-Category, X-Route-Pipeline.
Smart Brush: Keep / Remove#
To fix a result, send the original image plus masks the size of the image (after EXIF orientation):
keep_mask: light (white, opaque) pixels mark what must stay.remove_mask: marked pixels become transparent. Where both masks mark a pixel, Remove wins.matte(optional, needs a mask): the matte this server returned for this image. It is edited instead of recomputed, so earlier fixes are kept. Without it, the image is matted first and then edited.
A pixel counts as marked when it is light (luminance 128 or more after compositing onto black): white strokes on black, or on a transparent background, both work. Edits work at object level: a short Remove stroke across an object removes all of it. The server keeps no state; send the photo with every edit.
Both endpoints take Smart Brush masks (multipart or JSON on /v1/remove-background, JSON on /v1/remove-background/base64).
Typical editor loop: show the cutout, let the user paint Keep / Remove strokes, send image + strokes + the last matte, show the new result, repeat.
POST /v1/remove-background/base64#
Base64 image in, base64 image out. For clients that speak JSON only (browsers, workflow tools, serverless functions). Same model and same Smart Brush as above.
Request, Content-Type: application/json:
| Field | Required | Meaning |
|---|---|---|
image | yes | The photo, base64 (a data:image/...;base64, URL works too) |
keep_mask | no | Smart Brush: image the size of the photo, white pixels = keep |
remove_mask | no | Smart Brush: same, marked pixels become transparent. Remove wins over Keep |
matte | no | Needs a mask: the matte this endpoint returned for the photo, edited instead of recomputed |
output | no | cutout (default) or matte: what image holds in the response |
Response:
JSON
{
"image": "iVBORw0KGgo...",
"matte": "iVBORw0KGgo...",
"latencyMs": 812,
"routeCategory": "fine_strand",
"routePipeline": "matting"
}image is a base64 PNG, with no data: prefix: the transparent cutout, or the matte
when output is matte. matte is always the alpha matte; send it back with the next
Smart Brush edit.
Shell
B=$(base64 < photo.jpg | tr -d '\n')
curl -s -H 'Content-Type: application/json' -d "{\"image\": \"$B\"}" \
localhost:8000/v1/remove-background/base64 | jq -r .image | base64 -d > cutout.pngErrors are {"detail": "..."} with the same statuses as below.
Errors#
| Status | When | Body |
|---|---|---|
400 | Not an image, empty body | {"error": "..."} (binary) or {"detail": "..."} (JSON) |
422 | Invalid mask or matte (not an image, or not the image's size), or matte without a mask | same |
422 | output other than cutout / matte; /base64 body without image | {"detail": [...]} (validation list) |
503 | Model still loading | {"error": ...} / {"detail": "Model not ready"} |
Retry 503 after a short wait; 400 and 422 fail the same way again.
Each container processes one image at a time; concurrent requests wait in line. Set the client timeout to 120 s or more: a large photo on a busy container waits for the ones ahead of it.
This page as markdown: /pro-model-self-host/docs/api.md. Not a customer yet? Pro Model Self-Host.