Servidor de API · Mac
Tu Mac ahora es un servidor de generación de imágenes
Inicia el servidor de API en Private Diffusion y tu Mac responderá a solicitudes de imágenes de Claude, scripts y cualquier app compatible con la API de imágenes de OpenAI. Cada imagen se crea en tu Mac, sin ningún intermediario en la nube.
- Solo Mac
- Beta
Configúralo con tu agente de IA
Pega este prompt en Claude Code o en cualquier agente de programación. El agente comprueba que el servidor de API de tu Mac esté en ejecución y, después, configura MCP o un script en tu propio código.
Download https://privatediffusion.ai/agent-setup.md with curl, read it in full, and follow it to connect me to the Private Diffusion API server on my Mac.
API de generación de imágenes compatible con OpenAI, servida desde tu Mac
El código accede a ella mediante la API de imágenes de OpenAI y Claude mediante MCP. En ambos casos, el servidor de API ejecuta los modelos que ya has descargado y devuelve las imágenes terminadas.
Compatible con OpenAI
Configura un SDK de OpenAI para que apunte a tu Mac y llama a images.generate. La mayor parte del código de imágenes escrito para OpenAI cambia en dos sitios: la URL base y la clave.
Claude se conecta mediante MCP
Añade Private Diffusion a Claude Code o Claude Desktop y pídele una imagen a Claude. Llama a la herramienta generate_image, y tu Mac crea la imagen y la devuelve.
Creado en tu Mac
Los prompts y las imágenes viajan entre tu cliente y tu Mac, sin ningún intermediario en la nube. Cualquier dispositivo que pueda acceder a tu Mac puede enviarle solicitudes, y solo responde a las que llevan tu clave.
Configúralo en tres pasos
- 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
Inicia el servidor de API
Haz clic en Start API Server en la pestaña API Server, o usa el menú Server (⇧⌘A). Para que se ejecute cada vez que se abra la app, activa "Start the API server at launch" en Settings › API Server.
- 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 en claro, 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 "Start the API server at launch" 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 no entra en reposo 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 las imágenes de una en una. 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.pngPython (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 lanza 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",
"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"
}
}
}
}Requiere Node.js. La versión del puente está fijada.
Herramientas MCP
| Herramienta | Qué hace |
|---|---|
generate_image | Genera de una a 4 imágenes a partir de un prompt. Acepta los campos HTTP salvo quality y streaming, y devuelve jpeg con la compresión establecida en 85, salvo que pidas PNG. Un modelo explícito que no está listo genera un error, no recurre a otro modelo. |
list_models | Muestra los modelos listos en este Mac con los tamaños, pasos y factores de escalado que acepta cada uno aquí. |
get_image_chunk | La usan los clientes MCP que muestran imágenes a tamaño completo. Nunca la llamas tú mismo. |
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.
| Parámetro | Valores | Predeterminado | Notas |
|---|---|---|---|
prompt | string | Obligatorio | Qué dibujar. No puede estar vacío. |
model | string | Modelo activo | Un ID de modelo de la tabla siguiente. Un ID desconocido, no descargado o no compatible con este Mac recurre al modelo activo, y el model de la respuesta indica cuál se ejecutó. |
n | 1–4 | 1 | Cuántas imágenes. Cada una usa la siguiente semilla. |
size | "auto" | "WxH" | "auto" | Se ajusta al tamaño compatible más cercano del modelo, primero por forma y después por área. "auto" elige 1024×1024 cuando el modelo lo permite. Los tamaños extragrandes necesitan un Mac con más memoria. |
quality | "auto" | "low" | "medium" | "high" | "auto" | Solo "high" cambia el resultado, intercambiando velocidad por detalle. No afecta a Nanosaur 2 ni a MOSS-Image. |
output_format | "png" | "jpeg" | "png" | El formato de archivo de imagen. |
output_compression | 0–100 | 100 | Compresión para salida JPEG. 100 comprime menos. |
seed | integer | Aleatorio | Establécelo para repetir un resultado. |
negative_prompt | string | Ninguno | Qué excluir de la imagen. Solo algunos modelos; el resto devuelve 400. MOSS-Image lo acepta, pero solo lo interpreta en Quality. |
steps | integer | Predeterminado del modelo | Debe estar dentro del rango del modelo. Los modelos de pasos fijos solo aceptan su propio valor. MOSS-Image solo acepta 50, que ejecuta Quality; omite steps para su modo 4-step, que necesita tener instalado su adaptador. |
upscale | 1.5 | 2 | 4 | Ninguno | Amplía la imagen después de crearla. El modelo debe ofrecer el factor y su ampliador debe estar descargado, o la solicitud devuelve 400. Nanosaur 2 no tiene ampliador. En los Mac con menos memoria, 4 pasa a ser 2. |
stream | boolean | false | Envía el resultado como eventos enviados por el servidor, con vistas previas opcionales en todos los modelos salvo Nanosaur 2. |
partial_images | 0–3 | 0 | Cuántas vistas previas transmitir antes de la imagen final. Solo se usa con stream. Nanosaur 2 envía únicamente la imagen final. |
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 mensaje indica su evento y contiene un objeto JSON.
| Evento | Datos |
|---|---|
image_generation.partial_image | type, b64_json, partial_image_index, created_at, watermarkedUna vista previa mientras se forma la imagen. El índice se reinicia en 0 para cada imagen. |
image_generation.completed | type, b64_json, seed, watermarked, sensitive, created_atLa imagen terminada con su semilla. Una por imagen cuando pides más de una. |
error | errorAlgo falló después de abrirse el stream. Los errores anteriores llegan como una respuesta JSON normal. |
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 ID 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.
| Modelo | Id | Prompt negativo | Pasos | Escalado |
|---|---|---|---|---|
| Anima | anima | No | 8-12, predeterminado: 8 | 2× |
| Flux.2 Klein 4B | klein | Sí | 4 | 1,5× y 2× |
| Nanosaur 2 | nanosaur2 | No | 4 | No |
| Mage Flow Turbo | mage-flow-turbo | No | 4 | 1,5× y 2× |
| MOSS-Image | moss-image | Sí | 4 de forma predeterminada con su adaptador (6 en XL), o 50 para Quality | 1,5× y 2× |
| Krea 2 Turbo | krea2-turbo | No | 8 | 2× |
| Kroma Turbo | kroma | Sí | 8-12, predeterminado: 10 | 2× |
| Z-Image-Turbo | zit | Sí | 9 | 2× y 4× |
| Juggernaut Z Fast | juggernaut-z | Sí | 8 | 2× y 4× |
| ERNIE Image Turbo | ernie-turbo | No | 8 | 1,5× y 2× |
| Chroma1-Flash | chroma | Sí | 12 | 2× y 4× |
| Boogu Image Turbo | boogu | No | 4 | 2× y 4× |
Krea 2 Turbo siempre se ejecuta en 8 pasos mediante la API con el adaptador desactivado, independientemente de cómo esté configurado Studio.
Si omites steps, MOSS-Image ejecuta su modo 4-step (seis pasos en XL) si su adaptador está instalado, y Quality si no lo está. Envía steps: 50 para Quality, que tarda mucho más y es el único modo que interpreta negative_prompt; cualquier otro valor de steps devuelve 400.
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
}
}| Estado | Tipo y código | Cuándo |
|---|---|---|
| 400 | invalid_request_error | Falta un campo o está fuera de rango, o el cuerpo no es JSON válido. Cuando el problema está en un campo, param lo indica. |
| 401 | invalid_request_error · invalid_api_key | La clave falta o es incorrecta. |
| 404 | invalid_request_error · not_found | La ruta o el método no existe. |
| 405 | — | Se envió una solicitud distinta de POST a /mcp. |
| 413 | invalid_request_error · request_too_large | El cuerpo supera 2 MiB. |
| 429 | rate_limit_error · queue_full | La cola ya contiene 8 solicitudes. Inténtalo de nuevo dentro de poco. |
| 500 | server_error · generation_failed · internal_error | La generación falló en el Mac. |
| 503 | server_error · server_stopping · runtime_unavailable · model_unavailable | El servidor se está deteniendo, el motor necesita un momento o no hay ningún modelo activo. Vuelve a intentarlo tras los segundos de Retry-After. |
- Cuerpos de solicitud de hasta 2 MiB.
- De una a 4 imágenes por solicitud.
- Imágenes de una en una, con hasta 8 en espera.
- Cada 503 incluye
Retry-Afterde 10 segundos.
Preguntas frecuentes
Conecta Claude Code o Claude Desktop a Private Diffusion mediante MCP con la dirección y clave de Details, en la pestaña API Server de la app. Después pídele una imagen a Claude. Claude llama a Private Diffusion, que crea la imagen en tu Mac y la devuelve.
Sí, para generar imágenes. Apunta un SDK de OpenAI a la dirección de tu Mac con tu clave, y la llamada de generación de imágenes funciona como con OpenAI. Las diferencias: las imágenes vuelven como base64, no hay edición ni entrada de imagen, y obtienes campos adicionales como una semilla y un prompt negativo.
Sí. Cualquier dispositivo que pueda acceder a tu Mac puede usarlo con tu clave. Usa la dirección de Details, en la pestaña API Server de la app.
No. El servidor usa HTTP sin cifrar, así que úsalo en redes de confianza, mantén la clave privada y regenérala si se filtra.
Todos los modelos que hayas descargado en tu Mac. Cada uno conserva sus propias reglas para pasos, prompts negativos y escalado, indicadas en la tabla de esta página.
Tu Mac genera las imágenes de una en una. Hasta 8 solicitudes esperan en cola, y la siguiente recibe un error 429 hasta que avance la cola. De forma predeterminada, los SDK de OpenAI reintentan ese error dos veces antes de abandonar.
No. El servidor de API forma parte de Private Diffusion para Mac. En iPhone y iPad, generas imágenes en la propia app.