Dein Mac ist jetzt eine Bildgenerierungs-API

In drei Schritten einrichten

1. 1

   Ein Modell herunterladen

   Öffne Private Diffusion auf deinem Mac und lade mindestens ein Modell herunter. Der Server generiert mit den Modellen, die du hast, und das in Studio aktive Modell ist der Standard.

2. 2

   API-Server starten

   Klicke im Tab API-Server auf API-Server starten oder nutze das Menü Server (⇧⌘A). Damit dein Mac den Server bei jedem Öffnen der App bereitstellt, aktiviere in Einstellungen › API-Server "API-Server beim Start starten".

3. 3

   Deine Adresse und deinen Schlüssel kopieren

   Klicke im Tab API Server auf Details. Dort findest du die Adressen deines Mac, deinen Schlüssel und fertige Befehle für curl, Claude Code und Claude Desktop, jeweils mit beiden Angaben.

Vor dem Verbinden wissen

• Der Server verwendet reines HTTP. Dein Schlüssel, deine Prompts und Bilder werden unverschlüsselt über das Netzwerk übertragen. Nutze ihn daher nur in Netzwerken, denen du vertraust, und stoppe ihn in öffentlichem WLAN.
• Jedes Gerät, das deinen Mac erreichen kann und den Schlüssel hat, kann Bilder generieren.
• Behandle den Schlüssel wie ein Passwort. Wenn er preisgegeben wird, generiere ihn in Settings › API Server neu. Clients mit dem alten Schlüssel funktionieren erst wieder, wenn du ihnen den neuen gibst.
• Jede Webseite, der du den Schlüssel gibst, kann den Server über deinen Browser aufrufen. Füge ihn nur in Tools ein, denen du vertraust.
• Wenn "API-Server beim Start starten" aktiviert ist, stellt dein Mac den Server in jedem Netzwerk bereit, dem er beitritt. Deaktiviere es auf einem Laptop, der unterwegs ist.
• Während der Server läuft, pausiert Studio, dein Mac bleibt wach und das Wechseln oder Löschen von Modellen wartet, bis du ihn stoppst.
• Über die API erstellte Bilder landen in deiner Galerie. Aktiviere Incognito Mode oder deaktiviere Save API images to gallery, damit sie nicht dort erscheinen.
• Dein Mac erstellt immer nur ein Bild. Bis zu 8 Anfragen warten, und die nächste erhält einen Fehler queue_full.

Bilder mit curl, Python und JavaScript generieren

Jedes Beispiel erstellt ein Bild und speichert es als Datei. Lege deinen Schlüssel in einer Umgebungsvariablen namens PD_API_KEY ab und ersetze your-mac.local durch die Adresse deines Mac aus Details im Tab API Server.

8963 ist der Standardport. Wenn du ihn in Settings › API Server geändert hast, verwende deinen.

curl

Sendet den Prompt und dekodiert das zurückgegebene Bild mit 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)

Verwendet das offizielle Paket openai. Felder, die die OpenAI API nicht definiert, etwa seed, gehören in extra_body. Das SDK versucht bei einer vollen Warteschlange standardmäßig zweimal erneut, bevor es den Fehler auslöst.

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)

Läuft in Node.js mit dem Paket openai, das zusätzliche Felder wie seed unverändert sendet. Führe es nie auf einer Webseite aus, wo jeder den Schlüssel lesen könnte.

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-Bildgenerierung über MCP: Claude Code und Claude Desktop

Private Diffusion unterstützt das Model Context Protocol unter /mcp. Verbinde Claude einmal und bitte dann in natürlicher Sprache um Bilder.

Claude Code

Wenn PD_API_KEY wie oben festgelegt ist, führe dies einmal im Terminal aus, um den Server zu Claude Code hinzuzufügen.

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

Füge --scope project nicht hinzu. Dadurch wird dein Schlüssel in eine zur Weitergabe bestimmte Datei .mcp.json geschrieben.

Claude Desktop

Claude Desktop erreicht den Server über mcp-remote, eine kleine Bridge, die auf Node.js läuft. Öffne in Claude Desktop Settings › Developer › Edit Config, füge diesen Eintrag hinzu, ersetze pd-your-key durch deinen Schlüssel und starte Claude neu.

{
  "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"
      }
    }
  }
}

Benötigt Node.js. Die Bridge-Version ist festgelegt.

MCP-Tools

Authentifizierung

Jede Anfrage an /v1/* und /mcp übermittelt deinen Schlüssel im Header Authorization: Bearer pd-…. Die App erstellt den Schlüssel beim ersten Start des Servers. Du kannst ihn in Settings › API Server anzeigen oder neu generieren.

Ein fehlender oder falscher Schlüssel gibt 401 mit dem Code invalid_api_key zurück.

Endpunkte: /v1/images/generations, /v1/models und /mcp

POST /v1/images/generations

Generiert Bilder aus einem Text-Prompt. Anfragen und Antworten folgen der OpenAI-Bild-API, mit einigen eigenen Feldern.

Antwort

Bilder werden als base64 in b64_json zurückgegeben, nie als URL, jeweils mit ihrem seed und der Angabe, ob sie ein Wasserzeichen tragen. model nennt das verwendete Modell.

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

Gestreamte Teilbilder

Setze stream auf true, und der Server antwortet mit Server-Sent Events. Jeder Frame benennt sein Ereignis und enthält ein JSON-Objekt.

Der Stream wird nach dem letzten Bild geschlossen. Es gibt kein separates done-Ereignis.

GET /v1/models

Listet die Modelle auf, die auf diesem Mac heruntergeladen, bereit und unterstützt sind. Sende eine ihrer IDs als model.

Welche Modelle über die API funktionieren

Jedes Private Diffusion-Modell funktioniert über die API, sobald es heruntergeladen ist und dein Mac es unterstützt. Sende die ID aus der zweiten Spalte als model.

Krea 2 Turbo läuft über die API immer mit 8 Schritten, auch wenn Studio auf den schnelleren 4-Schritte-Modus eingestellt ist.

Größen und Upscale-Faktoren hängen vom Arbeitsspeicher deines Mac ab. Das MCP-Tool list_models meldet, was dein Mac akzeptiert.

Fehler und Limits

Fehler folgen dem OpenAI-Format: ein JSON-Objekt mit einer Nachricht, einem Typ, dem fehlerhaften Parameter und einem Code.

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

• Anfrage-Bodys bis 2 MiB.
• Ein bis 4 Bilder pro Anfrage.
• Ein Bild gleichzeitig, mit bis zu 8 wartenden Anfragen.
• Jede 503-Antwort enthält Retry-After mit 10 Sekunden.

FAQ