Сервер API · Mac

# Ваш Mac теперь API генерации изображений

Запустите сервер API в Private Diffusion, и ваш Mac будет отвечать на запросы изображений от Claude, из скриптов и от любого приложения, поддерживающего OpenAI image API. Каждое изображение создается на вашем Mac, без облачного посредника.

-   Только Mac
-   Бета

[![Предзаказ в App Store](/app-store/pre-order-badge/ru/pre-order.svg)![Предзаказ в App Store](/app-store/pre-order-badge/ru/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

На этой странице

1.  [Обзор](#overview)
2.  [Настройка](#setup)
3.  [Перед подключением](#before-you-connect)
4.  [Примеры](#examples)
5.  [Claude и MCP](#mcp)
6.  [Аутентификация](#authentication)
7.  [Эндпоинты](#endpoints)
8.  [Модели](#models)
9.  [Ошибки и ограничения](#errors)
10.  [FAQ](#faq)

## Совместимый с OpenAI API генерации изображений на вашем Mac

Код обращается к нему через OpenAI image API, а Claude - через MCP. В обоих случаях сервер API запускает уже загруженные вами модели и возвращает готовые изображения.

### Совместимость с OpenAI

Направьте OpenAI SDK на свой Mac и вызовите `images.generate`. Большинство кода для изображений, написанного для OpenAI, меняется в двух местах: базовый URL и ключ.

### Claude подключается через MCP

Добавьте Private Diffusion в Claude Code или Claude Desktop, затем попросите Claude создать картинку. Он вызовет инструмент `generate_image`, а ваш Mac создаст изображение и вернет его.

### Создано на вашем Mac

Промпты и изображения передаются между вашим клиентом и Mac без облачного посредника. Любое устройство, способное подключиться к вашему Mac, может отправлять запросы, а он отвечает только на запросы с вашим ключом.

## Настройка за три шага

1.  1
    
    ### Загрузите модель
    
    Откройте Private Diffusion на Mac и загрузите хотя бы одну модель. Сервер генерирует с доступными у вас моделями, а активная в Studio используется по умолчанию.
    
2.  2
    
    ### Запустите сервер API
    
    Нажмите Start API Server на вкладке API Server или воспользуйтесь меню Server (⇧⌘A). Чтобы сервер запускался при каждом открытии приложения, включите "Start the API server at launch" в Settings › API Server.
    
3.  3
    
    ### Скопируйте адрес и ключ
    
    Нажмите Details на вкладке API Server. Там указаны адреса вашего Mac, ключ и готовые команды для `curl`, Claude Code и Claude Desktop, в которых уже заполнены оба значения.
    

## Что нужно знать перед подключением

-   Сервер использует обычный HTTP. Ваш ключ, промпты и изображения передаются по сети без шифрования, поэтому запускайте его только в доверенных сетях и останавливайте в публичных Wi-Fi.
-   Любое устройство, которое может подключиться к вашему Mac и имеет ключ, может генерировать изображения.
-   Относитесь к ключу как к паролю. Если он утек, сгенерируйте новый в Settings › API Server. Клиенты со старым ключом перестанут работать, пока вы не дадите им новый.
-   Любая веб-страница, которой вы дали ключ, может обращаться к серверу из браузера. Вставляйте его только в инструменты, которым доверяете.
-   Когда включено "Start the API server at launch", ваш Mac обслуживает запросы в каждой сети, к которой подключается. Отключайте эту настройку на ноутбуке, который берете с собой.
-   Пока сервер работает, Studio приостанавливается, ваш Mac не засыпает, а смена или удаление моделей ждет остановки сервера.
-   Изображения, созданные через API, попадают в вашу галерею. Включите Incognito Mode или отключите Save API images to gallery, чтобы они туда не попадали.
-   Ваш Mac создает по одному изображению за раз. До 8 запросов ждут своей очереди, а следующий получит ошибку `queue_full`.

## Генерация изображений из `curl`, Python и JavaScript

Каждый пример создает одну картинку и сохраняет ее в файл. Поместите ключ в переменную окружения с именем `PD_API_KEY` и замените `your-mac.local` на адрес вашего Mac из Details на вкладке API Server.

8963 - порт по умолчанию. Если вы изменили его в Settings › API Server, используйте свой.

### curl

Отправляет промпт и декодирует возвращенное изображение с помощью `jq`.

curlКопировать

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

Использует официальный пакет `openai`. Поля, не определенные OpenAI API, например `seed`, передаются в `extra_body`. По умолчанию SDK дважды повторяет попытку при полной очереди, а затем возвращает ошибку.

PythonКопировать

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

Работает в Node.js с пакетом `openai`, который передает дополнительные поля, такие как `seed`, без изменений. Никогда не запускайте его на веб-странице - там любой сможет прочитать ключ.

JavaScriptКопировать

```
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 через MCP: Claude Code и Claude Desktop

Private Diffusion поддерживает Model Context Protocol по адресу `/mcp`. Подключите Claude один раз, затем запрашивайте изображения обычным языком.

### Claude Code

После настройки `PD_API_KEY`, как указано выше, один раз выполните эту команду в терминале, чтобы добавить сервер в Claude Code.

ТерминалКопировать

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

Не добавляйте `--scope project`. Он записывает ваш ключ в файл `.mcp.json`, предназначенный для общего доступа.

### Claude Desktop

Claude Desktop подключается к серверу через `mcp-remote` - небольшой мост, работающий на Node.js. В Claude Desktop откройте Settings › Developer › Edit Config, добавьте эту запись, замените `pd-your-key` своим ключом и перезапустите Claude.

claude\_desktop\_config.jsonКопировать

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

Требуется Node.js. Версия моста зафиксирована.

### Инструменты MCP

Инструменты MCP
| Инструмент | Что делает |
| --- | --- |
| `generate_image` | Создает от одного до 4 изображений по промпту. Принимает HTTP-поля, кроме `quality` и streaming, и возвращает `jpeg` со сжатием 85, если не запросить PNG. Явно указанная, но не готовая модель вызывает ошибку, а не переключение на другую модель. |
| `list_models` | Выводит список готовых на этом Mac моделей с поддерживаемыми здесь размерами, шагами и коэффициентами апскейла. |
| `get_image_chunk` | Используется MCP-клиентами, которые показывают изображения в полном размере. Вам никогда не нужно вызывать его самостоятельно. |

## Аутентификация

Каждый запрос к `/v1/*` и `/mcp` передает ваш ключ в заголовке `Authorization: Bearer pd-…`. Приложение создает ключ при первом запуске сервера. Показать или сгенерировать новый ключ можно в Settings › API Server.

При отсутствии или неверном ключе возвращается 401 с кодом `invalid_api_key`.

## Эндпоинты: `/v1/images/generations`, `/v1/models` и `/mcp`

### `POST /v1/images/generations`

Генерирует изображения по текстовому промпту. Запросы и ответы соответствуют OpenAI image API с несколькими собственными полями.

Параметры запроса
| Параметр | Значения | По умолчанию | Примечания |
| --- | --- | --- | --- |
| `prompt` | string | Обязательно | Что нарисовать. Не должен быть пустым. |
| `model` | string | Активная модель | Идентификатор модели из таблицы ниже. Неизвестный, не загруженный или не поддерживаемый на этом Mac идентификатор переключается на активную модель, а поле `model` в ответе указывает, какая модель была запущена. |
| `n` | 1–4 | `1` | Сколько изображений создать. Для каждого используется следующий seed. |
| `size` | "auto" | "WxH" | `"auto"` | Привязывается к ближайшему поддерживаемому моделью размеру: сначала по форме, затем по площади. `"auto"` выбирает 1024×1024, если модель это поддерживает. Для очень больших размеров нужен Mac с большим объемом памяти. |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | Только `"high"` меняет результат, жертвуя скоростью ради детализации. |
| `output_format` | "png" | "jpeg" | `"png"` | Формат файла изображения. |
| `output_compression` | 0–100 | `100` | Сжатие для JPEG. 100 сжимает меньше всего. |
| `seed` | integer | Случайно | Укажите, чтобы повторить результат. |
| `negative_prompt` | string | Нет | Что не включать в изображение. Поддерживается только некоторыми моделями, остальные вернут 400. |
| `steps` | integer | По умолчанию для модели | Должен находиться в диапазоне модели. Модели с фиксированным числом шагов принимают только собственное значение. |
| `upscale` | 1.5 | 2 | 4 | Нет | Увеличивает изображение после создания. Модель должна поддерживать этот коэффициент, а ее апскейлер должен быть загружен, иначе запрос вернет 400. На Mac с меньшим объемом памяти 4 становится 2. |
| `stream` | boolean | `false` | Отправляет результат как server-sent events с необязательными превью. |
| `partial_images` | 0–3 | `0` | Сколько превью передавать до финального изображения. Используется только с `stream`. |

#### Ответ

Изображения возвращаются как base64 в `b64_json`, а не как URL, каждое со своим `seed` и указанием на наличие водяного знака. `model` указывает использованную модель.

JSONКопировать

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

### Потоковая передача частичных изображений

Установите для `stream` значение true, и сервер ответит server-sent events. Каждый кадр указывает свое событие и содержит объект JSON.

Потоковая передача частичных изображений
| Событие | Данные |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Превью в процессе создания изображения. Индекс начинается с 0 для каждого изображения.

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

Готовое изображение со своим seed. По одному на каждое изображение, если вы запросили несколько.

 |
| `error` | `error`

Что-то пошло не так после открытия потока. Ошибки до этого приходят как обычный JSON-ответ.

 |

Поток закрывается после последнего изображения. Отдельного события done нет.

### `GET /v1/models`

Выводит список моделей, которые загружены, готовы и поддерживаются на этом Mac. Передайте один из их ID как `model`.

## Какие модели работают через API

Каждая модель Private Diffusion работает через API после загрузки, если ваш Mac ее поддерживает. Передайте идентификатор из второго столбца как `model`.

Какие модели работают через API
| Модель | ID | Негативный промпт | Шаги | Апскейл |
| --- | --- | --- | --- | --- |
| Anima | `anima` | Нет | 8-12, по умолчанию 8 | 2× |
| Flux.2 Klein 4B | `klein` | Да | 4 | 1,5×, 2× |
| Mage Flow Turbo | `mage-flow-turbo` | Нет | 4 | 1,5×, 2× |
| Krea 2 Turbo | `krea2-turbo` | Нет | 8 | 2× |
| Kroma Turbo | `kroma` | Да | 8-12, по умолчанию 10 | 2× |
| Z-Image-Turbo | `zit` | Да | 9 | 2×, 4× |
| Juggernaut Z Fast | `juggernaut-z` | Да | 8 | 2×, 4× |
| ERNIE Image Turbo | `ernie-turbo` | Нет | 8 | 1,5×, 2× |
| Chroma1-Flash | `chroma` | Да | 12 | 2×, 4× |
| Boogu Image Turbo | `boogu` | Нет | 4 | 2×, 4× |

Krea 2 Turbo всегда выполняет 8 шагов через API, даже если в Studio выбран более быстрый режим на 4 шага.

Размеры и коэффициенты апскейла зависят от объема памяти вашего Mac. Инструмент MCP `list_models` сообщает, что поддерживает ваш Mac.

## Ошибки и ограничения

Ошибки соответствуют формату OpenAI: объект JSON с сообщением, типом, параметром с ошибкой и кодом.

JSONКопировать

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

Ошибки и ограничения
| Статус | Тип и код | Когда |
| --- | --- | --- |
| 400 | invalid\_request\_error | Поле отсутствует или выходит за допустимый диапазон либо тело запроса содержит некорректный JSON. Если ошибка в одном поле, его указывает `param`. |
| 401 | invalid\_request\_error · invalid\_api\_key | Ключ отсутствует или неверен. |
| 404 | invalid\_request\_error · not\_found | Путь или метод не существует. |
| 405 | — | Запрос с методом, отличным от `POST`, был отправлен на `/mcp`. |
| 413 | invalid\_request\_error · request\_too\_large | Тело запроса больше 2 MiB. |
| 429 | rate\_limit\_error · queue\_full | В очереди уже 8 запросов. Повторите попытку чуть позже. |
| 500 | server\_error · generation\_failed · internal\_error | Генерация на Mac завершилась ошибкой. |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | Сервер останавливается, движку нужно немного времени или нет активной модели. Повторите попытку через число секунд из `Retry-After`. |

-   Тела запросов до 2 MiB.
-   От одного до 4 изображений в запросе.
-   Одно изображение за раз, до 8 ожидают.
-   Каждый ответ 503 содержит `Retry-After` со значением 10 секунд.

## FAQ

-   ### Как генерировать изображения с Claude?
    
    Подключите Claude Code или Claude Desktop к Private Diffusion через MCP, используя адрес и ключ из Details на вкладке API Server в приложении. Затем попросите Claude создать картинку. Claude вызовет Private Diffusion, который создаст изображение на вашем Mac и вернет его.
    
-   ### Совместим ли он с OpenAI image API?
    
    Да, для генерации изображений. Укажите в OpenAI SDK адрес вашего Mac и ключ, и вызов генерации изображений будет работать так же, как с OpenAI. Отличия: изображения возвращаются в base64, редактирование и входные изображения не поддерживаются, а также доступны дополнительные поля, такие как seed и негативный промпт.
    
-   ### Могут ли его использовать другие устройства в моей сети?
    
    Да. Любое устройство, которое может подключиться к вашему Mac, может использовать его с вашим ключом. Используйте адрес из Details на вкладке API Server в приложении.
    
-   ### Зашифровано ли соединение?
    
    Нет. Сервер использует обычный HTTP, поэтому используйте его в доверенных сетях, держите ключ в секрете и сгенерируйте новый, если он утек.
    
-   ### Какие модели работают через API?
    
    Все модели, которые вы загрузили на Mac. Для каждой действуют собственные правила по шагам, негативным промптам и апскейлу, перечисленные в таблице на этой странице.
    
-   ### Что происходит, когда несколько запросов поступают одновременно?
    
    Ваш Mac создает по одному изображению за раз. До 8 запросов ждут в очереди, а следующий получает ошибку 429, пока очередь не сдвинется. OpenAI SDK по умолчанию дважды повторяют попытку при этой ошибке, прежде чем прекратить.
    
-   ### Работает ли это на iPhone или iPad?
    
    Нет. Сервер API - часть Private Diffusion для Mac. На iPhone и iPad изображения создаются в самом приложении.
    

На этой странице

1.  [Обзор](#overview)
2.  [Настройка](#setup)
3.  [Перед подключением](#before-you-connect)
4.  [Примеры](#examples)
5.  [Claude и MCP](#mcp)
6.  [Аутентификация](#authentication)
7.  [Эндпоинты](#endpoints)
8.  [Модели](#models)
9.  [Ошибки и ограничения](#errors)
10.  [FAQ](#faq)