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.
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.
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/version | GET | Health check and backend version (public). |
/api/models | GET | List models, defaults, capabilities, and installed status. |
/api/loras | GET | Filter adapters by canonical base_model. |
/api/loras/{name}/compatibility | GET | Preflight an adapter against a model query param. |
/api/generate | POST | Queue a generation; returns job_id (or HTTP 429). |
/api/jobs/{job_id} | GET | Poll status, progress, and result metadata. |
/api/images/{id}/file | GET | Download original PNG/JPEG bytes (supports ?token=). |
/api/jobs/{job_id}/cancel | POST | Cooperative cancellation. |
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.