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

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

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 -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 дважды повторяет попытку при полной очереди, а затем возвращает ошибку.

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, без изменений. Никогда не запускайте его на веб-странице - там любой сможет прочитать ключ.

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.

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

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

Инструменты 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 с несколькими собственными полями.

Ответ

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

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

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

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

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

GET /v1/models

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

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

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

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

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

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

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

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

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

FAQ