Twój Mac jest teraz API generowania obrazów

Skonfiguruj w trzech krokach

1. 1

   Pobierz model

   Otwórz Private Diffusion na Macu i pobierz co najmniej jeden model. Serwer generuje przy użyciu dostępnych modeli, a model aktywny w Studio jest domyślny.

2. 2

   Uruchom serwer API

   Kliknij Uruchom serwer API na karcie Serwer API albo użyj menu Serwer (⇧⌘A). Aby serwer uruchamiał się przy każdym otwarciu aplikacji, włącz w Ustawienia › Serwer API opcję "Uruchamiaj serwer API przy starcie".

3. 3

   Skopiuj adres i klucz

   Kliknij Details na karcie API Server. Znajdziesz tam adresy Maca, klucz oraz gotowe polecenia dla curl, Claude Code i Claude Desktop, z uzupełnionymi obiema wartościami.

Co warto wiedzieć przed połączeniem

• Serwer używa zwykłego HTTP. Klucz, prompty i obrazy przesyłane są przez sieć bez szyfrowania, więc używaj go tylko w zaufanych sieciach i zatrzymuj w publicznej sieci Wi-Fi.
• Każde urządzenie, które może połączyć się z Maciem i ma klucz, może generować obrazy.
• Traktuj klucz jak hasło. Jeśli wycieknie, wygeneruj nowy w Settings › API Server. Klienci używający starego klucza przestaną działać, dopóki nie podasz im nowego.
• Każda strona internetowa, której podasz klucz, może wywoływać serwer z przeglądarki. Wklejaj go tylko do zaufanych narzędzi.
• Gdy opcja "Uruchamiaj serwer API przy starcie" jest włączona, Twój Mac obsługuje żądania w każdej sieci, do której się łączy. Wyłącz ją na laptopie, który zabierasz ze sobą.
• Gdy serwer działa, Studio jest wstrzymane, Mac pozostaje aktywny, a zmiana lub usunięcie modeli czeka na zatrzymanie serwera.
• Obrazy utworzone przez API trafiają do galerii. Włącz Incognito Mode albo wyłącz Save API images to gallery, aby ich tam nie zapisywać.
• Mac tworzy jeden obraz naraz. Do 8 żądań czeka w kolejce, a następne otrzymuje błąd queue_full.

Generuj obrazy z curl, Python i JavaScript

Każdy przykład tworzy jeden obraz i zapisuje go jako plik. Umieść klucz w zmiennej środowiskowej o nazwie PD_API_KEY i zastąp your-mac.local adresem Maca z Details na karcie API Server.

8963 to domyślny port. Jeśli zmieniono go w Settings › API Server, użyj swojego.

curl

Wysyła prompt i dekoduje zwrócony obraz za pomocą 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)

Korzysta z oficjalnego pakietu openai. Pola, których API OpenAI nie definiuje, takie jak seed, trafiają do extra_body. SDK domyślnie dwukrotnie ponawia próbę przy pełnej kolejce, a potem zgłasza błąd.

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)

Działa w Node.js z pakietem openai, który wysyła dodatkowe pola, takie jak seed, bez zmian. Nigdy nie uruchamiaj go na stronie internetowej, gdzie każdy mógłby odczytać klucz.

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"));

Generowanie obrazów Claude przez MCP: Claude Code i Claude Desktop

Private Diffusion obsługuje Model Context Protocol pod adresem /mcp. Połącz Claude raz, a potem proś o obrazy zwykłym językiem.

Claude Code

Po ustawieniu PD_API_KEY jak powyżej uruchom raz w terminalu to polecenie, aby dodać serwer do Claude Code.

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

Nie dodawaj --scope project. Zapisuje klucz w pliku .mcp.json przeznaczonym do udostępniania.

Claude Desktop

Claude Desktop łączy się z serwerem przez mcp-remote, niewielki mostek działający w Node.js. W Claude Desktop otwórz Settings › Developer › Edit Config, dodaj ten wpis, zastąp pd-your-key swoim kluczem i uruchom ponownie 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"
      }
    }
  }
}

Wymaga Node.js. Wersja mostka jest przypięta.

Narzędzia MCP

Uwierzytelnianie

Każde żądanie do /v1/* i /mcp przekazuje klucz w nagłówku Authorization: Bearer pd-…. Aplikacja tworzy klucz przy pierwszym uruchomieniu serwera. Wyświetl go lub wygeneruj nowy w Settings › API Server.

Brakujący lub nieprawidłowy klucz zwraca 401 z kodem invalid_api_key.

Endpointy: /v1/images/generations, /v1/models i /mcp

POST /v1/images/generations

Generuje obrazy z tekstowego promptu. Żądania i odpowiedzi są zgodne z OpenAI image API, z kilkoma własnymi polami.

Odpowiedź

Obrazy wracają jako base64 w b64_json, nigdy jako URL, każdy z własnym seed oraz informacją, czy zawiera znak wodny. model wskazuje uruchomiony model.

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

Częściowe obrazy strumieniowane

Ustaw stream na true, a serwer odpowie zdarzeniami wysyłanymi przez serwer. Każda ramka podaje swoje zdarzenie i zawiera obiekt JSON.

Strumień zamyka się po ostatnim obrazie. Nie ma osobnego zdarzenia done.

GET /v1/models

Wyświetla modele pobrane, gotowe i obsługiwane na tym Macu. Wyślij jeden z ich identyfikatorów jako model.

Które modele działają przez API

Każdy model Private Diffusion działa przez API po pobraniu, jeśli obsługuje go Twój Mac. Prześlij identyfikator z drugiej kolumny jako model.

Krea 2 Turbo zawsze wykonuje przez API 8 kroków, nawet gdy w Studio ustawiony jest szybszy tryb 4 kroków.

Rozmiary i współczynniki powiększania zależą od pamięci Maca. Narzędzie MCP list_models podaje, co akceptuje Mac.

Błędy i limity

Błędy mają format OpenAI: obiekt JSON z komunikatem, typem, parametrem powodującym błąd i kodem.

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

• Treść żądania do 2 MiB.
• Od jednego do 4 obrazów na żądanie.
• Jeden obraz naraz, z maksymalnie 8 oczekującymi.
• Każdy błąd 503 zawiera Retry-After z wartością 10 sekund.

FAQ