Il tuo Mac ora è un'API per la generazione di immagini

Configurazione in tre passaggi

1. 1

   Scarica un modello

   Apri Private Diffusion sul tuo Mac e scarica almeno un modello. Il server genera con i modelli che possiedi e quello attivo in Studio è il predefinito.

2. 2

   Avvia il server API

   Fai clic su Start API Server nella scheda API Server oppure usa il menu Server (⇧⌘A). Per avviarlo ogni volta che apri l'app, attiva "Start the API server at launch" in Impostazioni › API Server.

3. 3

   Copia indirizzo e chiave

   Fai clic su Details nella scheda API Server. Sono elencati gli indirizzi del tuo Mac, la tua chiave e comandi pronti per curl, Claude Code e Claude Desktop, già compilati.

Da sapere prima di connetterti

• Il server usa HTTP semplice. Chiave, prompt e immagini attraversano la rete senza crittografia, quindi usalo su reti affidabili e fermalo sulle reti Wi-Fi pubbliche.
• Qualsiasi dispositivo che può raggiungere il tuo Mac e possiede la chiave può generare immagini.
• Tratta la chiave come una password. Se viene divulgata, rigenerala in Settings › API Server. I client che usano la vecchia chiave smettono di funzionare finché non fornisci loro quella nuova.
• Qualsiasi pagina web a cui fornisci la chiave può chiamare il server dal browser. Incollala solo in strumenti affidabili.
• Con "Start the API server at launch" attivo, il tuo Mac è raggiungibile su ogni rete a cui si connette. Disattivalo su un portatile che porti in giro.
• Mentre il server è in esecuzione, Studio si mette in pausa, il tuo Mac resta attivo e il cambio o l'eliminazione dei modelli attende finché non lo fermi.
• Le immagini create tramite l'API finiscono nella tua galleria. Attiva Incognito Mode oppure disattiva Save API images to gallery per escluderle.
• Il tuo Mac crea un'immagine alla volta. Fino a 8 richieste attendono il proprio turno, mentre la successiva riceve un errore queue_full.

Genera immagini da curl, Python e JavaScript

Ogni esempio crea un'immagine e la salva come file. Inserisci la tua chiave in una variabile d'ambiente chiamata PD_API_KEY e sostituisci your-mac.local con l'indirizzo del tuo Mac indicato in Details nella scheda API Server.

8963 è la porta predefinita. Se l'hai modificata in Settings › API Server, usa la tua.

curl

Invia il prompt e decodifica l'immagine restituita 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 il pacchetto ufficiale openai. I campi non definiti dall'API OpenAI, come seed, vanno in extra_body. Per impostazione predefinita, l'SDK ritenta due volte una coda piena, poi restituisce l'errore.

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)

Funziona in Node.js con il pacchetto openai, che invia i campi aggiuntivi come seed senza modificarli. Non eseguirlo mai in una pagina web, dove chiunque potrebbe leggere la chiave.

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

Generazione di immagini con Claude via MCP: Claude Code e Claude Desktop

Private Diffusion usa il Model Context Protocol in /mcp. Connetti Claude una volta, poi chiedi immagini in linguaggio naturale.

Claude Code

Con PD_API_KEY impostata come sopra, esegui questo comando una volta nel terminale per aggiungere il server a Claude Code.

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

Non aggiungere --scope project. Scrive la tua chiave in un file .mcp.json destinato alla condivisione.

Claude Desktop

Claude Desktop raggiunge il server tramite mcp-remote, un piccolo bridge eseguito su Node.js. In Claude Desktop, apri Settings › Developer › Edit Config, aggiungi questa voce, sostituisci pd-your-key con la tua chiave e riavvia 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"
      }
    }
  }
}

Richiede Node.js. La versione del bridge è fissata.

Strumenti MCP

Autenticazione

Ogni richiesta a /v1/* e /mcp include la tua chiave nell'header Authorization: Bearer pd-…. L'app crea la chiave al primo avvio del server. Visualizzala o rigenerala in Settings › API Server.

Una chiave mancante o errata restituisce 401 con il codice invalid_api_key.

Endpoint: /v1/images/generations, /v1/models e /mcp

POST /v1/images/generations

Genera immagini da un prompt di testo. Richieste e risposte seguono l'API immagini di OpenAI, con alcuni campi propri.

Risposta

Le immagini vengono restituite come base64 in b64_json, mai come URL, ognuna con il proprio seed e l'indicazione se contiene una filigrana. model indica il modello eseguito.

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

Immagini parziali in streaming

Imposta stream su true e il server risponde con eventi inviati dal server. Ogni frame indica il proprio evento e contiene un oggetto JSON.

Lo stream si chiude dopo l'ultima immagine. Non esiste un evento finale separato.

GET /v1/models

Elenca i modelli scaricati, pronti e supportati su questo Mac. Invia uno dei loro ID come model.

Quali modelli funzionano con l'API

Ogni modello di Private Diffusion funziona tramite l'API una volta scaricato e se il tuo Mac lo supporta. Invia l'id della seconda colonna come model.

Krea 2 Turbo esegue sempre 8 passaggi tramite l'API, anche quando Studio è impostato sulla modalità più veloce a 4 passaggi.

Le dimensioni e i fattori di upscaling dipendono dalla memoria del tuo Mac. Lo strumento MCP list_models indica ciò che il tuo Mac accetta.

Errori e limiti

Gli errori seguono il formato OpenAI: un oggetto JSON con un messaggio, un tipo, il parametro errato e un codice.

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

• Corpi delle richieste fino a 2 MiB.
• Da una a 4 immagini per richiesta.
• Un'immagine alla volta, con fino a 8 richieste in attesa.
• Ogni 503 include Retry-After di 10 secondi.

FAQ