DiffusionBear

Local REST API · Apple Silicon · v0.5.0

Local agentic image generation API on Mac.

DiffusionBear exposes a FastAPI endpoint on http://127.0.0.1:8001. Agents send a prompt, poll a job, and retrieve the rendered PNG/JPEG bytes using mostly 4-bit MLX weights.

127.0.0.1:8001 · No key on loopback (API mode OFF) · SHA-256 dbk_ Bearer / X-API-Key for remote/API mode · 1 job at a time · HTTP 429 when queue is full

For Claude Code / Cursor / Antigravity

Paste this into your agent's system prompt.

You can generate images locally via DiffusionBear at http://127.0.0.1:8001. Use plain HTTP/JSON.
1. GET /api/models -> pick an id with "installed": true.
2. POST /api/generate {model,prompt,width,height,steps} -> {job_id}. Send "model", never "base_model". Unknown fields are rejected.
3. Poll GET /api/jobs/{job_id} every 2s until status is done | error | cancelled.
4. GET /api/images/{id}/file -> save the bytes.
One job runs at a time; on HTTP 429 wait and retry.
If remote/API mode is on, send Authorization: Bearer dbk_...
FLUX.2-klein: no negative prompt. Keep the returned seed.
Download full spec (.md)

8 lines · ~160 tokens · matches v0.5.0 backend routes

Agent Workflow

Three calls, plain HTTP/JSON

01 / Discover

List installed models

GET /api/models returns model ids, capabilities, defaults, and installed. Pick a runnable model such as flux1-schnell.

02 / Generate

Submit a job

POST /api/generate accepts prompt, size, steps, seed, and optional LoRA paths. Returns job_id immediately, or HTTP 429 if the queue is full.

03 / Retrieve

Poll and download

GET /api/jobs/{job_id} reports queued, generating, done, or error. Fetch bytes from /api/images/{id}/file.

Capabilities

Models, LoRAs, jobs, and real files

9 canonical model families

sdxl, flux1, flux2, flux3, krea2, z-image, qwen, moss, fibo2. Pony and Illustrious remain SDXL with display subtypes.

LoRA registry & preflight

GET /api/loras returns each adapter's base_model, triggers, scale, and path. Check compatibility via GET /api/loras/{name}/compatibility?model=....

Original PNG/JPEG bytes

GET /api/images/{id}/file returns the original image bytes instead of wrapping base64 inside JSON.

Python & curl

Minimal client

agent_generate.py

import time, requests

BASE = "http://127.0.0.1:8001"
models = requests.get(f"{BASE}/api/models").json()
model = next(m for m in models if m["id"] == "flux1-schnell" and m["installed"])

job = requests.post(f"{BASE}/api/generate", json={
    "model": model["id"],
    "prompt": "a red apple on a white table",
    "width": 512, "height": 768, "steps": 4,
}).json()

while True:
    s = requests.get(f"{BASE}/api/jobs/{job['job_id']}").json()
    if s["status"] in {"done", "error", "cancelled"}:
        break
    time.sleep(2)

img = s["results"][0]
data = requests.get(f"{BASE}/api/images/{img['id']}/file").content
open("output.png", "wb").write(data)

curl (Bearer / X-API-Key)

# 1. submit
curl -s http://127.0.0.1:8001/api/generate \
  -H 'Authorization: Bearer dbk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"model":"flux1-schnell","prompt":"a red apple","width":512,"height":768,"steps":4}'

# 2. poll (X-API-Key also works)
curl -s -H 'X-API-Key: dbk_your_key' \
  http://127.0.0.1:8001/api/jobs/<job_id>

# 3. download
curl -s -H 'Authorization: Bearer dbk_your_key' \
  http://127.0.0.1:8001/api/images/<id>/file -o image.png

Endpoint Map

Generation surface

Endpoint Method Purpose
/api/versionGETHealth check and backend version (public).
/api/modelsGETList models, defaults, capabilities, and installed status.
/api/lorasGETFilter adapters by canonical base_model.
/api/loras/{name}/compatibilityGETPreflight an adapter against a model query param.
/api/generatePOSTQueue a generation; returns job_id (or HTTP 429).
/api/jobs/{job_id}GETPoll status, progress, and result metadata.
/api/images/{id}/fileGETDownload original PNG/JPEG bytes (supports ?token=).
/api/jobs/{job_id}/cancelPOSTCooperative cancellation.

Send model, not base_model, to /api/generate. Unknown fields are rejected by the strict request schema.

Remote Access & Limits

Platform limits, stated plainly

Tailscale / LAN browser access

Create a dbk_ key in Parameters → API (stored as SHA-256), turn API mode ON, and expose 127.0.0.1:8001 via tailscale serve --bg --https=443 http://127.0.0.1:8001 (or --host 0.0.0.0 on a private LAN; wildcard bind falls back to loopback without a 16+ char key). Leave Backend URL empty in the remote browser so requests stay same-origin.

Workstation constraints

DiffusionBear is a local workstation tool, not a cloud cluster. It processes one heavy generation at a time, requires Apple Silicon (macOS 26.2+), and requires model weights to be downloaded before the first run.

FAQ

Questions

How does an AI agent generate images locally on a Mac?

Call the local DiffusionBear API at http://127.0.0.1:8001: GET /api/models, POST /api/generate, then poll GET /api/jobs/{job_id} and download the result from /api/images/{id}/file.

Does DiffusionBear require a cloud API key?

No cloud key is required. Loopback requests need no key; a v0.5.0 PRO deployment requires a local API key via Authorization: Bearer or security.json.

Can agents use LoRAs through the local API?

Yes. GET /api/loras returns canonical base_model families such as flux1 and sdxl; pass the returned path and a scale in the generation loras array.

Is the API safe to expose on a network?

The default is loopback-only. v0.5.0 adds Bearer/X-API-Key authentication, a bind fail-safe, and a generation rate limiter. Non-loopback deployments still require TLS at a reverse proxy or Tailscale Serve.

How can I generate remotely with only one web browser (Chrome, Firefox, Opera, Safari)?

DiffusionBear serves its full React studio UI from the Mac. Create a managed dbk_ key per device in Parameters -> API, turn API mode ON, expose 127.0.0.1:8001 via tailscale serve --bg --https=443 http://127.0.0.1:8001 (or launch CLI with --host 0.0.0.0 on private LAN), open that URL in Chrome, Firefox, Opera (with Opera VPN OFF), or Safari, leave Backend URL empty, paste your key, then click Test and Save connection.

Why should Backend URL stay empty when using a remote browser?

Empty means the same origin that served the web page. When you open the Mac's HTTPS or LAN URL directly in Chrome, Firefox, Opera, or Safari, leaving Backend URL empty keeps all API calls and gallery image requests strictly same-origin. Only set a non-local URL when running your local Mac UI as a CLIENT pointing to another Mac.