# 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](/pro-model-self-host/docs/ai-assistants)).

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

```bash
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.

```bash
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`:

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

```bash
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

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