Tu Mac ahora es una API de generación de imágenes

Configúralo en tres pasos

1. 1

   Descarga un modelo

   Abre Private Diffusion en tu Mac y descarga al menos un modelo. El servidor genera con los modelos que tienes, y el que está activo en Studio es el predeterminado.

2. 2

   Inicia el servidor de API

   Haz clic en Iniciar servidor de API en la pestaña Servidor de API, o usa el menú Servidor (⇧⌘A). Para que se ejecute cada vez que se abra la app, activa "Iniciar el servidor de API al abrir" en Ajustes › Servidor de API.

3. 3

   Copia tu dirección y clave

   Haz clic en Details en la pestaña API Server. Muestra las direcciones de tu Mac, tu clave y comandos listos para usar de curl, Claude Code y Claude Desktop con ambos valores rellenados.

Lo que debes saber antes de conectarte

• El servidor usa HTTP sin cifrar. Tu clave, los prompts y las imágenes cruzan la red sin cifrado, así que úsalo en redes de confianza y detenlo en redes Wi-Fi públicas.
• Cualquier dispositivo que pueda acceder a tu Mac y tenga la clave puede generar imágenes.
• Trata la clave como una contraseña. Si se filtra, regenérala en Settings › API Server. Los clientes que usan la clave anterior dejarán de funcionar hasta que les des la nueva.
• Cualquier página web a la que des la clave puede llamar al servidor desde tu navegador. Pégala solo en herramientas de confianza.
• Con "Iniciar el servidor de API al abrir" activado, tu Mac ofrece el servicio en todas las redes a las que se conecta. Desactívalo en un portátil con el que viajes.
• Mientras el servidor está activo, Studio se pausa, tu Mac permanece despierto y el cambio o la eliminación de modelos espera hasta que lo detengas.
• Las imágenes creadas mediante la API llegan a tu galería. Activa Incognito Mode o desactiva Save API images to gallery para mantenerlas fuera.
• Tu Mac crea una imagen a la vez. Hasta 8 solicitudes esperan su turno, y la siguiente recibe un error queue_full.

Genera imágenes desde curl, Python y JavaScript

Cada ejemplo crea una imagen y la guarda como archivo. Pon tu clave en una variable de entorno llamada PD_API_KEY y sustituye your-mac.local por la dirección de tu Mac en Details, en la pestaña API Server.

8963 es el puerto predeterminado. Si lo cambiaste en Settings › API Server, usa el tuyo.

curl

Envía el prompt y decodifica la imagen devuelta con 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)

Usa el paquete oficial openai. Los campos que no define la API de OpenAI, como seed, se incluyen en extra_body. De forma predeterminada, el SDK reintenta una cola llena dos veces y luego genera el error.

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)

Se ejecuta en Node.js con el paquete openai, que envía campos adicionales como seed tal cual. No lo ejecutes nunca en una página web, donde cualquiera podría leer la clave.

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

Generación de imágenes con Claude mediante MCP: Claude Code y Claude Desktop

Private Diffusion usa el Model Context Protocol en /mcp. Conecta Claude una vez y luego pide imágenes en lenguaje natural.

Claude Code

Con PD_API_KEY configurada como se indica arriba, ejecuta esto una vez en tu terminal para añadir el servidor a Claude Code.

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

No añadas --scope project. Escribe tu clave en un archivo .mcp.json pensado para compartirse.

Claude Desktop

Claude Desktop accede al servidor mediante mcp-remote, un pequeño puente que se ejecuta en Node.js. En Claude Desktop, abre Settings › Developer › Edit Config, añade esta entrada, sustituye pd-your-key por tu clave y reinicia 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"
      }
    }
  }
}

Requiere Node.js. La versión del puente está fijada.

Herramientas MCP

Autenticación

Cada solicitud a /v1/* y /mcp lleva tu clave en la cabecera Authorization: Bearer pd-…. La app crea la clave la primera vez que se inicia el servidor. Muéstrala o regénérala en Settings › API Server.

Una clave ausente o incorrecta devuelve 401 con el código invalid_api_key.

Endpoints: /v1/images/generations, /v1/models y /mcp

POST /v1/images/generations

Genera imágenes a partir de un prompt de texto. Las solicitudes y respuestas siguen la API de imágenes de OpenAI, con algunos campos propios.

Respuesta

Las imágenes vuelven como base64 en b64_json, nunca como URL, cada una con su seed y si lleva una marca de agua. model indica el modelo que se ejecutó.

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

Imágenes parciales en streaming

Establece stream en true y el servidor responde con eventos enviados por el servidor. Cada fotograma indica su evento y contiene un objeto JSON.

El stream se cierra tras la última imagen. No hay un evento done independiente.

GET /v1/models

Lista los modelos descargados, listos y compatibles con este Mac. Envía uno de sus ids como model.

Qué modelos funcionan con la API

Todos los modelos de Private Diffusion funcionan mediante la API una vez descargados y siempre que tu Mac los admita. Envía el id de la segunda columna como model.

Krea 2 Turbo siempre se ejecuta con 8 pasos a través de la API, incluso cuando Studio está configurado en su modo más rápido de 4 pasos.

Los tamaños y factores de escalado dependen de la memoria de tu Mac. La herramienta MCP list_models informa de lo que acepta tu Mac.

Errores y límites

Los errores siguen el formato de OpenAI: un objeto JSON con un mensaje, un tipo, el parámetro problemático y un código.

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

• Cuerpos de solicitud de hasta 2 MiB.
• De una a 4 imágenes por solicitud.
• Una imagen a la vez, con hasta 8 esperando.
• Cada 503 incluye Retry-After de 10 segundos.

Preguntas frecuentes