Local API#

Hosts#

• Mac: enable Local API in the withoutBG for Mac menu bar or Settings. Base URL http://127.0.0.1:8000.
• Docker: service-cpu / service-gpu on port 8000.
• Headless Mac (CI): /mac/headless

Endpoints#

• GET /health: liveness
• GET /openapi.json: live OpenAPI from the running server. Canonical copy: /openapi/local-api.json
• POST /v1/remove-background: cutout or matte

Query param ?output=cutout|matte (default cutout).

Request body: raw image bytes, or multipart field image. Response: PNG plus X-Latency-Ms header.

Examples#

curl cutout#

curl -sS -X POST \
  'http://127.0.0.1:8000/v1/remove-background?output=cutout' \
  -H 'Content-Type: image/jpeg' \
  --data-binary @input.jpg \
  -o cutout.png

curl matte#

curl -sS -X POST \
  'http://127.0.0.1:8000/v1/remove-background?output=matte' \
  -F 'image=@input.jpg' \
  -o matte.png

Python#

import urllib.request

url = "http://127.0.0.1:8000/v1/remove-background?output=cutout"
with open("input.jpg", "rb") as f:
    data = f.read()
req = urllib.request.Request(url, data=data, method="POST")
req.add_header("Content-Type", "image/jpeg")
with urllib.request.urlopen(req) as resp:
    open("cutout.png", "wb").write(resp.read())

Errors#

• 400: invalid or missing image
• 500: inference failure
• Connection refused: Local API not running (start Mac app Local API or Docker service)

GIMP plugin#

Point the GIMP plugin at http://127.0.0.1:8000 while Local API is running.

Privacy#

Local API binds to loopback. Open Model inference stays on device. Optional Cloud (Pro Model) calls are a separate path with an API key. See Privacy.

Related#

• Open Model vs Pro Model
• Pro Model API docs
• withoutBG for Mac