Serwer API · Mac

# Twój Mac jest teraz API generowania obrazów

Uruchom serwer API w Private Diffusion, a Mac będzie odpowiadać na żądania obrazów z Claude, skryptów i każdej aplikacji obsługującej OpenAI image API. Każdy obraz powstaje na Mac, bez pośrednictwa chmury.

-   Tylko Mac
-   Beta

[![Zamów w przedsprzedaży w App Store](/app-store/pre-order-badge/pl/pre-order.svg)![Zamów w przedsprzedaży w App Store](/app-store/pre-order-badge/pl/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

Na tej stronie

1.  [Przegląd](#overview)
2.  [Konfiguracja](#setup)
3.  [Zanim się połączysz](#before-you-connect)
4.  [Przykłady](#examples)
5.  [Claude i MCP](#mcp)
6.  [Uwierzytelnianie](#authentication)
7.  [Endpointy](#endpoints)
8.  [Modele](#models)
9.  [Błędy i limity](#errors)
10.  [FAQ](#faq)

## Zgodne z OpenAI API generowania obrazów, obsługiwane z Maca

Kod łączy się przez OpenAI image API, a Claude przez MCP. W obu przypadkach serwer API uruchamia już pobrane modele i zwraca gotowe obrazy.

### Zgodne z OpenAI

Skieruj OpenAI SDK na swojego Maca i wywołaj `images.generate`. Większość kodu generowania obrazów napisanego dla OpenAI wymaga zmian w dwóch miejscach: podstawowym adresie URL i kluczu.

### Claude łączy się przez MCP

Dodaj Private Diffusion do Claude Code lub Claude Desktop, a następnie poproś Claude o obraz. Wywoła narzędzie `generate_image`, a Mac utworzy obraz i go zwróci.

### Tworzone na Macu

Prompty i obrazy przesyłane są między klientem a Maciem, bez pośrednictwa chmury. Każde urządzenie, które może połączyć się z Maciem, może wysyłać żądania, a Mac odpowiada tylko na te zawierające klucz.

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

curlKopiuj

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

PythonKopiuj

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

JavaScriptKopiuj

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

TerminalKopiuj

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

claude\_desktop\_config.jsonKopiuj

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

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

### Narzędzia MCP

Narzędzia MCP
| Narzędzie | Działanie |
| --- | --- |
| `generate_image` | Tworzy od jednego do 4 obrazów na podstawie promptu. Przyjmuje pola HTTP z wyjątkiem `quality` i streamingu oraz zwraca `jpeg` z kompresją ustawioną na 85, chyba że zażądasz PNG. Jawnie wskazany model, który nie jest gotowy, powoduje błąd, a nie użycie modelu zastępczego. |
| `list_models` | Wyświetla modele gotowe na tym Macu wraz z obsługiwanymi przez każdy rozmiarami, liczbą kroków i współczynnikami powiększania. |
| `get_image_chunk` | Używane przez klientów MCP wyświetlających obrazy w pełnym rozmiarze. Nigdy nie wywołujesz go samodzielnie. |

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

Parametry żądania
| Parametr | Wartości | Domyślnie | Uwagi |
| --- | --- | --- | --- |
| `prompt` | string | Wymagane | Co narysować. Nie może być puste. |
| `model` | string | Aktywny model | Identyfikator modelu z tabeli poniżej. Nieznany identyfikator, model niepobrany lub nieobsługiwany na tym Macu powoduje użycie aktywnego modelu, a `model` w odpowiedzi wskazuje model, który uruchomiono. |
| `n` | 1–4 | `1` | Liczba obrazów. Każdy używa kolejnego seeda. |
| `size` | "auto" | "WxH" | `"auto"` | Dopasowuje do najbliższego rozmiaru obsługiwanego przez model, najpierw według kształtu, potem powierzchni. `"auto"` wybiera 1024×1024, gdy model na to pozwala. Bardzo duże rozmiary wymagają Maca z większą pamięcią. |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | Tylko `"high"` zmienia wynik, zamieniając szybkość na szczegółowość. |
| `output_format` | "png" | "jpeg" | `"png"` | Format pliku obrazu. |
| `output_compression` | 0–100 | `100` | Kompresja dla formatu JPEG. 100 oznacza najmniejszą kompresję. |
| `seed` | integer | Losowy | Ustaw, aby powtórzyć wynik. |
| `negative_prompt` | string | Brak | Co pominąć na obrazie. Tylko niektóre modele; pozostałe zwracają 400. |
| `steps` | integer | Domyślne ustawienie modelu | Musi mieścić się w zakresie modelu. Modele ze stałą liczbą kroków akceptują tylko własną wartość. |
| `upscale` | 1.5 | 2 | 4 | Brak | Powiększa obraz po jego utworzeniu. Model musi oferować dany współczynnik, a jego moduł powiększania musi być pobrany, w przeciwnym razie żądanie zwraca 400. Na Macach z mniejszą pamięcią 4 staje się 2. |
| `stream` | boolean | `false` | Wysyła wynik jako zdarzenia wysyłane przez serwer, z opcjonalnymi podglądami. |
| `partial_images` | 0–3 | `0` | Liczba podglądów do przesłania przed końcowym obrazem. Używane tylko z `stream`. |

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

JSONKopiuj

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

Częściowe obrazy strumieniowane
| Zdarzenie | Dane |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Podgląd podczas tworzenia obrazu. Indeks zaczyna się od 0 dla każdego obrazu.

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

Gotowy obraz z seedem. Jeden na obraz, gdy poprosisz o więcej niż jeden.

 |
| `error` | `error`

Coś nie powiodło się po otwarciu strumienia. Błędy przed jego otwarciem trafiają jako zwykła odpowiedź 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`.

Które modele działają przez API
| Model | Id | Negatywny prompt | Kroki | Powiększanie |
| --- | --- | --- | --- | --- |
| Anima | `anima` | Nie | 8-12, domyślnie 8 | 2× |
| Flux.2 Klein 4B | `klein` | Tak | 4 | 1,5× i 2× |
| Mage Flow Turbo | `mage-flow-turbo` | Nie | 4 | 1,5× i 2× |
| Krea 2 Turbo | `krea2-turbo` | Nie | 8 | 2× |
| Kroma Turbo | `kroma` | Tak | 8-12, domyślnie 10 | 2× |
| Z-Image-Turbo | `zit` | Tak | 9 | 2× i 4× |
| Juggernaut Z Fast | `juggernaut-z` | Tak | 8 | 2× i 4× |
| ERNIE Image Turbo | `ernie-turbo` | Nie | 8 | 1,5× i 2× |
| Chroma1-Flash | `chroma` | Tak | 12 | 2× i 4× |
| Boogu Image Turbo | `boogu` | Nie | 4 | 2× i 4× |

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.

JSONKopiuj

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

Błędy i limity
| Status | Typ i kod | Kiedy |
| --- | --- | --- |
| 400 | invalid\_request\_error | Brakuje pola, wartość pola jest poza dozwolonym zakresem lub treść nie jest prawidłowym JSON-em. Gdy błąd dotyczy jednego pola, wskazuje je `param`. |
| 401 | invalid\_request\_error · invalid\_api\_key | Klucz jest brakujący lub nieprawidłowy. |
| 404 | invalid\_request\_error · not\_found | Ścieżka lub metoda nie istnieje. |
| 405 | — | Żądanie inne niż `POST` zostało wysłane do `/mcp`. |
| 413 | invalid\_request\_error · request\_too\_large | Treść jest większa niż 2 MiB. |
| 429 | rate\_limit\_error · queue\_full | W kolejce jest już 8 żądań. Spróbuj ponownie za chwilę. |
| 500 | server\_error · generation\_failed · internal\_error | Generowanie na Macu nie powiodło się. |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | Serwer się zatrzymuje, silnik potrzebuje chwili lub nie ma aktywnego modelu. Ponów próbę po liczbie sekund podanej w `Retry-After`. |

-   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

-   ### Jak generować obrazy z Claude?
    
    Połącz Claude Code lub Claude Desktop z Private Diffusion przez MCP, używając adresu i klucza z Details na karcie API Server aplikacji. Potem poproś Claude o obraz. Claude wywoła Private Diffusion, które utworzy obraz na Macu i go zwróci.
    
-   ### Czy jest zgodne z OpenAI image API?
    
    Tak, w zakresie generowania obrazów. Skieruj pakiet SDK OpenAI na adres Maca, używając klucza, a wywołanie generowania obrazów zadziała tak jak z OpenAI. Różnice: obrazy wracają jako base64, nie ma edycji ani wejściowych obrazów, a dostępne są dodatkowe pola, takie jak seed i negatywny prompt.
    
-   ### Czy mogą z niego korzystać inne urządzenia w mojej sieci?
    
    Tak. Każde urządzenie, które może połączyć się z Maciem, może korzystać z niego za pomocą klucza. Użyj adresu z Details na karcie API Server aplikacji.
    
-   ### Czy połączenie jest szyfrowane?
    
    Nie. Serwer używa zwykłego HTTP, więc korzystaj z niego w zaufanych sieciach, zachowaj klucz w tajemnicy i wygeneruj nowy, jeśli wycieknie.
    
-   ### Które modele działają przez API?
    
    Każdy model pobrany na Maca. Każdy zachowuje własne zasady dotyczące kroków, negatywnych promptów i powiększania, wymienione w tabeli na tej stronie.
    
-   ### Co się dzieje, gdy kilka żądań przychodzi jednocześnie?
    
    Twój Mac tworzy po jednym obrazie naraz. W kolejce czeka do 8 żądań, a kolejne otrzymuje błąd 429, dopóki kolejka nie ruszy. SDK OpenAI domyślnie dwukrotnie ponawiają próbę przed rezygnacją.
    
-   ### Czy działa na iPhone lub iPad?
    
    Nie. Serwer API jest częścią Private Diffusion dla Mac. Na iPhone i iPad generujesz obrazy bezpośrednio w aplikacji.
    

Na tej stronie

1.  [Przegląd](#overview)
2.  [Konfiguracja](#setup)
3.  [Zanim się połączysz](#before-you-connect)
4.  [Przykłady](#examples)
5.  [Claude i MCP](#mcp)
6.  [Uwierzytelnianie](#authentication)
7.  [Endpointy](#endpoints)
8.  [Modele](#models)
9.  [Błędy i limity](#errors)
10.  [FAQ](#faq)