Your Mac Is Now an Image Generation API

Set It Up in Three Steps

1. 1

   Download a Model

   Open Private Diffusion on your Mac and download at least one model. The server generates with the models you have, and the one active in Studio is its default.

2. 2

   Start the API Server

   Click Start API Server in the API Server tab, or use the Server menu (⇧⌘A). To serve every time the app opens, turn on "Start the API server at launch" in Settings › API Server.

3. 3

   Copy Your Address and Key

   Click Details in the API Server tab. It lists your Mac's addresses, your key, and ready-made commands for curl, Claude Code, and Claude Desktop with both filled in.

Know Before You Connect

• The server speaks plain HTTP. Your key, prompts, and images cross the network unencrypted, so run it on networks you trust and stop it on public Wi-Fi.
• Any device that can reach your Mac and holds the key can generate images.
• Treat the key like a password. If it leaks, regenerate it in Settings › API Server. Clients using the old key stop working until you give them the new one.
• Any web page you give the key to can call the server from your browser. Paste it only into tools you trust.
• With "Start the API server at launch" turned on, your Mac serves on every network it joins. Turn it off on a laptop that travels.
• While the server runs, Studio pauses, your Mac stays awake, and switching or deleting models waits until you stop it.
• Images made over the API land in your gallery. Turn on Incognito Mode, or turn off Save API images to gallery, to keep them out.
• Your Mac makes one image at a time. Up to 8 requests wait their turn, and the next one gets a queue_full error.

Generate Images From curl, Python, and JavaScript

Each example makes one picture and saves it as a file. Put your key in an environment variable named PD_API_KEY, and replace your-mac.local with your Mac's address from Details in the API Server tab.

8963 is the default port. If you changed it in Settings › API Server, use yours.

curl

Sends the prompt and decodes the returned image with jq.

curl -sS http://your-mac.local:8963/v1/images/generations \
  -H "Authorization: Bearer $PD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at dusk, oil painting", "size": "1024x1024"}' \
  | jq -r '.data[0].b64_json // error(.error.message)' | base64 --decode > lighthouse.png

Python (OpenAI SDK)

Uses the official openai package. Fields the OpenAI API does not define, such as seed, go in extra_body. The SDK retries a full queue twice by default, then raises the error.

import base64
import os

from openai import OpenAI

client = OpenAI(
    base_url="http://your-mac.local:8963/v1",
    api_key=os.environ["PD_API_KEY"],
)

result = client.images.generate(
    prompt="a lighthouse at dusk, oil painting",
    size="1024x1024",
    extra_body={"seed": 42},
)

with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

JavaScript (OpenAI SDK, Node.js)

Runs in Node.js with the openai package, which sends extra fields such as seed as they are. Never run it in a web page, where anyone could read the key.

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://your-mac.local:8963/v1",
  apiKey: process.env.PD_API_KEY,
});

const result = await client.images.generate({
  prompt: "a lighthouse at dusk, oil painting",
  size: "1024x1024",
  seed: 42,
});

writeFileSync("lighthouse.png", Buffer.from(result.data[0].b64_json, "base64"));

Claude Image Generation Over MCP: Claude Code and Claude Desktop

Private Diffusion speaks the Model Context Protocol at /mcp. Connect Claude once, then ask for images in plain language.

Claude Code

With PD_API_KEY set as above, run this once in your terminal to add the server to Claude Code.

claude mcp add --transport http private-diffusion http://your-mac.local:8963/mcp \
  --header "Authorization: Bearer $PD_API_KEY"

Do not add --scope project. It writes your key into a .mcp.json file meant to be shared.

Claude Desktop

Claude Desktop reaches the server through mcp-remote, a small bridge that runs on Node.js. In Claude Desktop, open Settings › Developer › Edit Config, add this entry, replace pd-your-key with your key, and restart Claude.

{
  "mcpServers": {
    "private-diffusion": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "http://your-mac.local:8963/mcp",
        "--allow-http",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${PRIVATE_DIFFUSION_AUTH}"
      ],
      "env": {
        "PRIVATE_DIFFUSION_AUTH": "Bearer pd-your-key"
      }
    }
  }
}

Needs Node.js. The bridge version is pinned.

MCP Tools

Authentication

Every request to /v1/* and /mcp carries your key in the Authorization: Bearer pd-… header. The app creates the key the first time the server starts. Reveal or regenerate it in Settings › API Server.

A missing or wrong key returns 401 with the code invalid_api_key.

Endpoints: /v1/images/generations, /v1/models, and /mcp

POST /v1/images/generations

Generates images from a text prompt. Requests and responses follow the OpenAI image API, with a few fields of its own.

Response

Images come back as base64 in b64_json, never as a URL, each with its seed and whether it carries a watermark. model names the model that ran.

{
  "created": 1767225600,
  "model": "zit",
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…",
      "seed": 42,
      "watermarked": false,
      "sensitive": false
    }
  ]
}

Streaming Partial Images

Set stream to true and the server replies with server-sent events. Each frame names its event and carries a JSON object.

The stream closes after the last image. There is no separate done event.

GET /v1/models

Lists the models that are downloaded, ready, and supported on this Mac. Send one of their ids as model.

Which Models Work Over the API

Every Private Diffusion model works over the API once it is downloaded and your Mac supports it. Send the id from the second column as model.

Krea 2 Turbo always runs 8 steps over the API, even when Studio is set to its faster 4-step mode.

Sizes and upscale factors depend on your Mac's memory. The list_models MCP tool reports what your Mac accepts.

Errors and Limits

Errors follow the OpenAI shape: a JSON object with a message, a type, the parameter at fault, and a code.

{
  "error": {
    "message": "steps must be between 8 and 12 for Kroma Turbo.",
    "type": "invalid_request_error",
    "param": "steps",
    "code": null
  }
}

• Request bodies up to 2 MiB.
• One to 4 images per request.
• One image at a time, with up to 8 waiting.
• Every 503 carries Retry-After of 10 seconds.

FAQ