Servidor de API · Mac

# Tu Mac ahora es una API 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 relevo en la nube de por medio.

-   Solo Mac
-   Beta

[![Reserva en el App Store](/app-store/pre-order-badge/es/pre-order.svg)![Reserva en el App Store](/app-store/pre-order-badge/es/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

En esta página

1.  [Resumen](#overview)
2.  [Configuración](#setup)
3.  [Antes de conectarte](#before-you-connect)
4.  [Ejemplos](#examples)
5.  [Claude y MCP](#mcp)
6.  [Autenticación](#authentication)
7.  [Endpoints](#endpoints)
8.  [Modelos](#models)
9.  [Errores y límites](#errors)
10.  [Preguntas frecuentes](#faq)

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

curlCopiar

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

PythonCopiar

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

JavaScriptCopiar

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

TerminalCopiar

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

claude\_desktop\_config.jsonCopiar

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

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` | Lista los modelos listos en este Mac con los tamaños, pasos y factores de escalado que acepta cada uno aquí. |
| `get_image_chunk` | Lo 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ámetros de la solicitud
| 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, cambiando velocidad por detalle. |
| `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; los demás devuelven 400. |
| `steps` | integer | Predeterminado del modelo | Debe estar dentro del rango del modelo. Los modelos de pasos fijos solo aceptan su propio valor. |
| `upscale` | 1.5 | 2 | 4 | Ninguno | Amplía la imagen después de crearla. El modelo debe ofrecer el factor y su escalador debe estar descargado, o la solicitud devuelve 400. En 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. |
| `partial_images` | 0–3 | `0` | Cuántas vistas previas transmitir antes de la imagen final. Solo se usa con `stream`. |

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

JSONCopiar

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

Imágenes parciales en streaming
| Evento | Datos |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Una 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_at`

La imagen terminada con su semilla. Una por imagen cuando pides más de una.

 |
| `error` | `error`

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

Qué modelos funcionan con la API
| 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× |
| Mage Flow Turbo | `mage-flow-turbo` | No | 4 | 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 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.

JSONCopiar

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

Errores y límites
| 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.
-   Una imagen a la vez, con hasta 8 esperando.
-   Cada 503 incluye `Retry-After` de 10 segundos.

## Preguntas frecuentes

-   ### ¿Cómo genero imágenes con Claude?
    
    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.
    
-   ### ¿Es compatible con la API de imágenes de OpenAI?
    
    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.
    
-   ### ¿Pueden usarlo otros dispositivos de mi red?
    
    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.
    
-   ### ¿La conexión está cifrada?
    
    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.
    
-   ### ¿Qué modelos funcionan mediante la API?
    
    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.
    
-   ### ¿Qué ocurre cuando llegan varias solicitudes a la vez?
    
    Tu Mac genera una imagen a la vez. 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.
    
-   ### ¿Funciona en iPhone o iPad?
    
    No. El servidor de API forma parte de Private Diffusion para Mac. En iPhone y iPad, generas imágenes en la propia app.
    

En esta página

1.  [Resumen](#overview)
2.  [Configuración](#setup)
3.  [Antes de conectarte](#before-you-connect)
4.  [Ejemplos](#examples)
5.  [Claude y MCP](#mcp)
6.  [Autenticación](#authentication)
7.  [Endpoints](#endpoints)
8.  [Modelos](#models)
9.  [Errores y límites](#errors)
10.  [Preguntas frecuentes](#faq)