API-Server · Mac

# Dein Mac ist jetzt eine Bildgenerierungs-API

Starte den API-Server in Private Diffusion, und dein Mac beantwortet Bildanfragen von Claude, aus Skripten und aus jeder App, die die OpenAI-Bild-API unterstützt. Jedes Bild wird auf deinem Mac erstellt, ohne Cloud-Relay dazwischen.

-   Nur Mac
-   Beta

[![Im App Store vorbestellen](/app-store/pre-order-badge/de/pre-order.svg)![Im App Store vorbestellen](/app-store/pre-order-badge/de/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

Auf dieser Seite

1.  [Überblick](#overview)
2.  [Einrichtung](#setup)
3.  [Vor dem Verbinden](#before-you-connect)
4.  [Beispiele](#examples)
5.  [Claude und MCP](#mcp)
6.  [Authentifizierung](#authentication)
7.  [Endpunkte](#endpoints)
8.  [Modelle](#models)
9.  [Fehler und Limits](#errors)
10.  [FAQ](#faq)

## Mit OpenAI kompatible Bildgenerierungs-API von deinem Mac

Code erreicht sie über die OpenAI-Bild-API, Claude über MCP. In beiden Fällen führt der API-Server die bereits heruntergeladenen Modelle aus und liefert fertige Bilder zurück.

### OpenAI-kompatibel

Richte ein OpenAI SDK auf deinen Mac und rufe `images.generate` auf. Der meiste für OpenAI geschriebene Bildcode ändert sich an zwei Stellen: der Basis-URL und dem Schlüssel.

### Claude verbindet sich über MCP

Füge Private Diffusion zu Claude Code oder Claude Desktop hinzu und bitte Claude dann um ein Bild. Es ruft das Tool `generate_image` auf, und dein Mac erstellt das Bild und gibt es zurück.

### Auf deinem Mac erstellt

Prompts und Bilder werden zwischen deinem Client und deinem Mac übertragen, ohne Cloud-Relay. Jedes Gerät, das deinen Mac erreichen kann, kann Anfragen senden, und er beantwortet nur solche mit deinem Schlüssel.

## 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`.

curlKopieren

```
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.

PythonKopieren

```
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.

JavaScriptKopieren

```
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.

TerminalKopieren

```
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.

claude\_desktop\_config.jsonKopieren

```
{
  "mcpServers": {
    "private-diffusion": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.14.3",
        "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

MCP-Tools
| Tool | Funktion |
| --- | --- |
| `generate_image` | Erzeugt aus einem Prompt ein bis 4 Bilder. Akzeptiert die HTTP-Felder außer `quality` und Streaming und gibt `jpeg` mit auf 85 eingestellter Komprimierung zurück, sofern du nicht PNG anforderst. Ein explizit angegebenes Modell, das nicht bereit ist, führt zu einem Fehler, nicht zu einem Fallback. |
| `list_models` | Listet die auf diesem Mac bereiten Modelle mit den jeweils unterstützten Größen, Schritten und Upscale-Faktoren auf. |
| `get_image_chunk` | Wird von MCP-Clients verwendet, die Bilder in voller Größe anzeigen. Du rufst es nie selbst auf. |

## 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.

Anfrageparameter
| Parameter | Werte | Standard | Hinweise |
| --- | --- | --- | --- |
| `prompt` | string | Erforderlich | Was gezeichnet werden soll. Darf nicht leer sein. |
| `model` | string | Aktives Modell | Eine Modell-ID aus der Tabelle unten. Eine unbekannte, nicht heruntergeladene oder auf diesem Mac nicht unterstützte ID fällt auf das aktive Modell zurück, und `model` in der Antwort benennt das ausgeführte Modell. |
| `n` | 1–4 | `1` | Wie viele Bilder. Jedes verwendet den nächsten Seed. |
| `size` | "auto" | "WxH" | `"auto"` | Passt sich an die nächstgelegene vom Modell unterstützte Größe an, zuerst nach Form und dann nach Fläche. `"auto"` wählt 1024×1024, wenn das Modell dies zulässt. Besonders große Größen benötigen einen Mac mit mehr Arbeitsspeicher. |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | Nur `"high"` verändert das Ergebnis und tauscht Geschwindigkeit gegen Details. |
| `output_format` | "png" | "jpeg" | `"png"` | Das Bilddateiformat. |
| `output_compression` | 0–100 | `100` | Komprimierung für JPEG-Ausgabe. 100 komprimiert am wenigsten. |
| `seed` | integer | Zufällig | Setze ihn, um ein Ergebnis zu wiederholen. |
| `negative_prompt` | string | Keine | Was nicht im Bild sein soll. Nur einige Modelle unterstützen dies, die übrigen geben 400 zurück. |
| `steps` | integer | Modellstandard | Muss im Bereich des Modells liegen. Modelle mit festen Schritten akzeptieren nur ihren eigenen Wert. |
| `upscale` | 1.5 | 2 | 4 | Keine | Vergrößert das Bild nach der Erstellung. Das Modell muss den Faktor anbieten und sein Upscaler muss heruntergeladen sein, sonst gibt die Anfrage 400 zurück. Auf Macs mit weniger Arbeitsspeicher wird 4 zu 2. |
| `stream` | boolean | `false` | Sendet das Ergebnis als Server-Sent Events, mit optionalen Vorschauen. |
| `partial_images` | 0–3 | `0` | Wie viele Vorschauen vor dem fertigen Bild gestreamt werden. Wird nur mit `stream` verwendet. |

#### 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.

JSONKopieren

```
{
  "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.

Gestreamte Teilbilder
| Ereignis | Daten |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Eine Vorschau, während das Bild entsteht. Der Index beginnt für jedes Bild wieder bei 0.

 |
| `image_generation.completed` | `type, b64_json, seed, watermarked, sensitive, created_at`

Das fertige Bild mit seinem Seed. Eins pro Bild, wenn du mehr als eins anforderst.

 |
| `error` | `error`

Nach dem Öffnen des Streams ist etwas fehlgeschlagen. Fehler davor kommen als normale JSON-Antwort an.

 |

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`.

Welche Modelle über die API funktionieren
| Modell | ID | Negativer Prompt | Schritte | Upscale |
| --- | --- | --- | --- | --- |
| Anima | `anima` | Nein | 8-12, Standard 8 | 2× |
| Flux.2 Klein 4B | `klein` | Ja | 4 | 1,5× und 2× |
| Mage Flow Turbo | `mage-flow-turbo` | Nein | 4 | 1,5× und 2× |
| Krea 2 Turbo | `krea2-turbo` | Nein | 8 | 2× |
| Kroma Turbo | `kroma` | Ja | 8-12, Standard 10 | 2× |
| Z-Image-Turbo | `zit` | Ja | 9 | 2× und 4× |
| Juggernaut Z Fast | `juggernaut-z` | Ja | 8 | 2× und 4× |
| ERNIE Image Turbo | `ernie-turbo` | Nein | 8 | 1,5× und 2× |
| Chroma1-Flash | `chroma` | Ja | 12 | 2× und 4× |
| Boogu Image Turbo | `boogu` | Nein | 4 | 2× und 4× |

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.

JSONKopieren

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

Fehler und Limits
| Status | Typ und Code | Wann |
| --- | --- | --- |
| 400 | invalid\_request\_error | Ein Feld fehlt, liegt außerhalb des zulässigen Bereichs oder der Body ist kein gültiges JSON. Wenn ein einzelnes Feld den Fehler verursacht, wird es durch `param` benannt. |
| 401 | invalid\_request\_error · invalid\_api\_key | Der Schlüssel fehlt oder ist falsch. |
| 404 | invalid\_request\_error · not\_found | Der Pfad oder die Methode existiert nicht. |
| 405 | — | Eine andere Anfrage als `POST` wurde an `/mcp` gesendet. |
| 413 | invalid\_request\_error · request\_too\_large | Der Body ist größer als 2 MiB. |
| 429 | rate\_limit\_error · queue\_full | Die Warteschlange enthält bereits 8 Anfragen. Versuche es in Kürze erneut. |
| 500 | server\_error · generation\_failed · internal\_error | Die Generierung ist auf dem Mac fehlgeschlagen. |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | Der Server wird gestoppt, die Engine braucht einen Moment oder kein Modell ist aktiv. Versuche es nach den Sekunden im Header `Retry-After` erneut. |

-   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

-   ### Wie generiere ich Bilder mit Claude?
    
    Verbinde Claude Code oder Claude Desktop über MCP mit Private Diffusion, mit der Adresse und dem Schlüssel aus Details im Tab API Server der App. Bitte Claude dann um ein Bild. Claude ruft Private Diffusion auf, das das Bild auf deinem Mac erstellt und zurückgibt.
    
-   ### Ist sie mit der OpenAI-Bild-API kompatibel?
    
    Ja, zum Generieren von Bildern. Richte ein OpenAI SDK mit deinem Schlüssel auf die Adresse deines Mac, und der Aufruf zur Bildgenerierung funktioniert wie bei OpenAI. Die Unterschiede: Bilder werden als base64 zurückgegeben, es gibt keine Bearbeitung oder Bildeingabe, und du erhältst zusätzliche Felder wie einen Seed und einen negativen Prompt.
    
-   ### Können andere Geräte in meinem Netzwerk sie nutzen?
    
    Ja. Jedes Gerät, das deinen Mac erreichen kann, kann sie mit deinem Schlüssel nutzen. Verwende die Adresse aus Details im Tab API Server der App.
    
-   ### Ist die Verbindung verschlüsselt?
    
    Nein. Der Server verwendet reines HTTP. Nutze ihn daher nur in Netzwerken, denen du vertraust, halte den Schlüssel privat und generiere ihn neu, wenn er preisgegeben wird.
    
-   ### Welche Modelle funktionieren über die API?
    
    Jedes Modell, das du auf deinen Mac heruntergeladen hast. Jedes hat eigene Regeln für Schritte, negative Prompts und Upscaling, die in der Tabelle auf dieser Seite aufgeführt sind.
    
-   ### Was passiert, wenn mehrere Anfragen gleichzeitig eintreffen?
    
    Dein Mac erstellt immer nur ein Bild gleichzeitig. Bis zu 8 Anfragen warten in der Schlange, und die nächste erhält einen 429-Fehler, bis die Schlange weiterzieht. Die OpenAI SDKs versuchen diesen Fehler standardmäßig zweimal erneut, bevor sie aufgeben.
    
-   ### Funktioniert sie auf iPhone oder iPad?
    
    Nein. Der API-Server ist Teil von Private Diffusion für Mac. Auf iPhone und iPad generierst du Bilder direkt in der App.
    

Auf dieser Seite

1.  [Überblick](#overview)
2.  [Einrichtung](#setup)
3.  [Vor dem Verbinden](#before-you-connect)
4.  [Beispiele](#examples)
5.  [Claude und MCP](#mcp)
6.  [Authentifizierung](#authentication)
7.  [Endpunkte](#endpoints)
8.  [Modelle](#models)
9.  [Fehler und Limits](#errors)
10.  [FAQ](#faq)