lhk229/BGfilter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README HTTP service section into a full API reference

Browse Source 
- fix stale launch example (drop the D:\ lightML path -> generic uvicorn)
- add Endpoints, Authentication (X-Genarrative-Image-Token / BGFILTER_AUTH_TOKEN),
  request-field table, response-header table, and status-code table
- update examples to show the auth header and cross_check=off

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
孔令弘
2026-07-11 09:08:49 +00:00
parent 1861cb0199
commit 826ad09098
1 changed files with 58 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+58 -25
View File
@@ -178,46 +178,79 @@ metadata.json
An HTTP wrapper (`app.py` + `bgfilter/service.py`) exposes the pipeline as a
long-running FastAPI service. Models load once and are reused across requests.
For deploying to a Linux server (dependencies, weights, systemd, offline mode), see
[DEPLOY.md](DEPLOY.md).
```powershell
D:\MiniConda\envs\lightML\python.exe -m uvicorn app:app `
--host 127.0.0.1 --port 18083 --workers 1
```
Two endpoints:
- `GET /healthz` — liveness/config JSON.
- `POST /remove-background` — `multipart/form-data`, returns `image/png`.
- `file` (required) — the source image. The field name is fixed as `file`.
- `screen_color` (optional) — `#RRGGBB` prior; omit/empty for auto-detect.
- `seg_model` (optional) — `birefnet` (default) or `anime-seg`.
- `cross_check` (optional) — `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`);
per-request override of the cross-model veto. Omit/empty to use the service
default. The response reports the effective state in `X-BGFilter-Cross-Check`.
For deploying to a Linux server (dependencies, weights, systemd, offline mode, auth),
see [DEPLOY.md](DEPLOY.md).
```bash
# default (birefnet + auto background colour)
python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1
```
Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
### Endpoints
- **`GET /healthz`** — liveness + config JSON, e.g.
`{"ok":true,"service":"bgfilter","version":"0.1.0","defaultSegModel":"birefnet","device":"cpu","crossCheck":true}`.
Always unauthenticated.
- **`POST /remove-background`** — `multipart/form-data` in, `image/png` (RGBA) out.
### Authentication
Optional, opt-in via the `BGFILTER_AUTH_TOKEN` env var. When set, `/remove-background`
requires header **`X-Genarrative-Image-Token: <token>`** (constant-time compare); a
missing or wrong token returns `401`. When unset the endpoint is open (a fronting proxy
is expected to authenticate). `/healthz` is always open. See [DEPLOY.md](DEPLOY.md) §10.
### Request fields (`POST /remove-background`, `multipart/form-data`)
| Field | Required | Values | Meaning |
| --- | --- | --- | --- |
| `file` | yes | image file | Source image (field name fixed as `file`). |
| `screen_color` | no | `#RRGGBB`, or omit/empty/`auto` | Background-colour prior; omit to auto-detect from the border. |
| `seg_model` | no | `birefnet` (default) / `anime-seg` | Segmentation backend. |
| `cross_check` | no | `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`) | Per-request override of the cross-model veto; omit/empty = service default. |
### Response headers (on `200`)
| Header | Example | Meaning |
| --- | --- | --- |
| `X-BGFilter-Elapsed-Ms` | `2372` | Server-side processing time (ms). |
| `X-BGFilter-Seg-Model` | `birefnet` | Segmenter actually used. |
| `X-BGFilter-Screen-Color` | `#CFEFFF` / `auto` | Background colour used. |
| `X-BGFilter-Cross-Check` | `on` / `off` | Effective cross-check state. |
### Status codes
| Code | When |
| --- | --- |
| `200` | Success — body is the RGBA PNG. |
| `400` | Bad input: unreadable image, invalid `screen_color`/`seg_model`/`cross_check`, or auto-detect failed (pass `screen_color`). |
| `401` | Auth enabled and the token is missing or wrong. |
| `413` | Image exceeds `BGFILTER_MAX_IMAGE_PIXELS` (~4 MP by default). |
| `500` | Inference failed. |
| `503` | Service still loading models (not ready). |
### Examples
```bash
# default (birefnet + auto background colour); add the auth header if the service requires it
curl -sS -F "file=@input.png" \
-H "X-Genarrative-Image-Token: <token>" \
http://127.0.0.1:18083/remove-background -o output.png
# explicit background colour + anime segmenter
# explicit background colour + anime segmenter, cross-check off for this request
curl -sS \
-F "file=@input.png" \
-F "screen_color=#CFEFFF" \
-F "seg_model=anime-seg" \
http://127.0.0.1:18083/remove-background -o output.png
# enable the cross-model veto for this request only (see below; slow on CPU)
curl -sS -F "file=@input.png" -F "cross_check=1" \
-F "cross_check=off" \
http://127.0.0.1:18083/remove-background -o output.png
```
Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when present);
`BGFILTER_DEVICE` overrides both model and segmentation device; `BGFILTER_MAX_IMAGE_PIXELS`
caps input size (default ~4MP → `413`); `BGFILTER_PRELOAD=1` loads the default models at
startup. Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
startup; `BGFILTER_AUTH_TOKEN` gates the endpoint (see Authentication above).
Like the CLI, the service runs the **cross-model veto by default** (config
default: on); its HR-matting model is preloaded with the rest of the warm set.