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:

ClientUse
Server code with image bytesPOST /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 editoreither; /base64 returns the matte to send back with the next edit
MethodPathPurpose
POST/v1/remove-backgroundRemove the background, or fix a result with Smart Brush masks. Image bytes in, PNG out (or JSON, see below)
POST/v1/remove-background/base64Same, for JSON clients: base64 image in, base64 image out
GET/ready200 {"status":"ready"} once the model is loaded, 503 before
GET/healthLiveness: {"status":"ok","model":"withoutbg-pro-self-host","version":"10.12.4"} (the container's Docker HEALTHCHECK uses it)
GET/llms.txtThis API as plain text for AI coding assistants
GET/v1/licensesLicense 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:

NameDefaultMeaning
outputcutoutBinary 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.png

2. 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.png

3. 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:

FieldRequiredMeaning
imageyesThe photo, base64 (a data:image/...;base64, URL works too)
keep_masknoSmart Brush: image the size of the photo, white pixels = keep
remove_masknoSmart Brush: same, marked pixels become transparent. Remove wins over Keep
mattenoNeeds a mask: the matte this endpoint returned for the photo, edited instead of recomputed
outputnocutout (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.png

Errors are {"detail": "..."} with the same statuses as below.

Errors#

StatusWhenBody
400Not an image, empty body{"error": "..."} (binary) or {"detail": "..."} (JSON)
422Invalid mask or matte (not an image, or not the image's size), or matte without a masksame
422output other than cutout / matte; /base64 body without image{"detail": [...]} (validation list)
503Model 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.