Server API · Mac

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

Avvia il server API in Private Diffusion e il tuo Mac risponderà alle richieste di immagini da Claude, da script e da qualsiasi app compatibile con l'API immagini di OpenAI. Ogni immagine viene creata sul tuo Mac, senza passare dal cloud.

-   Solo Mac
-   Beta

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

In questa pagina

1.  [Panoramica](#overview)
2.  [Configurazione](#setup)
3.  [Prima di connetterti](#before-you-connect)
4.  [Esempi](#examples)
5.  [Claude e MCP](#mcp)
6.  [Autenticazione](#authentication)
7.  [Endpoint](#endpoints)
8.  [Modelli](#models)
9.  [Errori e limiti](#errors)
10.  [FAQ](#faq)

## API per la generazione di immagini compatibile con OpenAI, servita dal tuo Mac

Il codice la raggiunge tramite l'API immagini di OpenAI e Claude tramite MCP. In entrambi i casi, il server API esegue i modelli che hai già scaricato e restituisce immagini finite.

### Compatibile con OpenAI

Configura un SDK OpenAI per il tuo Mac e chiama `images.generate`. La maggior parte del codice per immagini scritto per OpenAI cambia in due punti: l'URL di base e la chiave.

### Claude si connette via MCP

Aggiungi Private Diffusion a Claude Code o Claude Desktop, poi chiedi a Claude un'immagine. Chiama lo strumento `generate_image` e il tuo Mac crea l'immagine e la restituisce.

### Creato sul tuo Mac

Prompt e immagini viaggiano tra il tuo client e il tuo Mac, senza passare dal cloud. Qualsiasi dispositivo che può raggiungere il tuo Mac può inviargli richieste, e risponde solo a quelle che includono la tua chiave.

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

curlCopia

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

PythonCopia

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

JavaScriptCopia

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

TerminaleCopia

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

claude\_desktop\_config.jsonCopia

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

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

### Strumenti MCP

Strumenti MCP
| Strumento | Cosa fa |
| --- | --- |
| `generate_image` | Genera da una a 4 immagini a partire da un prompt. Accetta i campi HTTP tranne `quality` e lo streaming, e restituisce `jpeg` con compressione impostata su 85, a meno che tu non richieda PNG. Un modello esplicitamente indicato ma non pronto genera un errore, non un fallback. |
| `list_models` | Elenca i modelli pronti su questo Mac con le dimensioni, i passaggi e i fattori di upscaling accettati da ciascuno. |
| `get_image_chunk` | Usato dai client MCP che visualizzano immagini a dimensione intera. Non lo chiami mai direttamente. |

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

Parametri della richiesta
| Parametro | Valori | Predefinito | Note |
| --- | --- | --- | --- |
| `prompt` | string | Obbligatorio | Cosa disegnare. Non può essere vuoto. |
| `model` | string | Modello attivo | Un ID modello dalla tabella qui sotto. Un ID sconosciuto, non scaricato o non supportato su questo Mac usa come fallback il modello attivo e il campo `model` della risposta indica quello eseguito. |
| `n` | 1–4 | `1` | Quante immagini creare. Ognuna usa il seed successivo. |
| `size` | "auto" | "WxH" | `"auto"` | Si adatta alla dimensione supportata più vicina dal modello, prima per forma e poi per area. `"auto"` seleziona 1024×1024 quando il modello lo consente. Le dimensioni molto grandi richiedono un Mac con più memoria. |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | Solo `"high"` modifica il risultato, privilegiando il dettaglio rispetto alla velocità. |
| `output_format` | "png" | "jpeg" | `"png"` | Il formato del file immagine. |
| `output_compression` | 0–100 | `100` | Compressione per l'output JPEG. 100 è la compressione minima. |
| `seed` | integer | Casuale | Impostalo per ripetere un risultato. |
| `negative_prompt` | string | Nessuno | Cosa escludere dall'immagine. Solo alcuni modelli; gli altri restituiscono 400. |
| `steps` | integer | Predefinito del modello | Deve rientrare nell'intervallo del modello. I modelli a passaggi fissi accettano solo il proprio valore. |
| `upscale` | 1.5 | 2 | 4 | Nessuno | Ingrandisce l'immagine dopo la creazione. Il modello deve offrire il fattore e il relativo upscaler deve essere scaricato, altrimenti la richiesta restituisce 400. Sui Mac con meno memoria, 4 diventa 2. |
| `stream` | boolean | `false` | Invia il risultato come eventi inviati dal server, con anteprime facoltative. |
| `partial_images` | 0–3 | `0` | Quante anteprime trasmettere prima dell'immagine finale. Usato solo con `stream`. |

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

JSONCopia

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

Immagini parziali in streaming
| Evento | Dati |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Un'anteprima mentre l'immagine si forma. L'indice riparte da 0 per ogni immagine.

 |
| `image_generation.completed` | `type, b64_json, seed, watermarked, sensitive, created_at`

L'immagine finita con il suo seed. Una per immagine quando ne richiedi più di una.

 |
| `error` | `error`

Qualcosa non è riuscito dopo l'apertura dello stream. Gli errori precedenti arrivano come normale risposta 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`.

Quali modelli funzionano con l'API
| Modello | ID | Prompt negativo | Passaggi | Upscaling |
| --- | --- | --- | --- | --- |
| Anima | `anima` | No | 8-12, predefinito 8 | 2× |
| Flux.2 Klein 4B | `klein` | Sì | 4 | 1,5× e 2× |
| Mage Flow Turbo | `mage-flow-turbo` | No | 4 | 1,5× e 2× |
| Krea 2 Turbo | `krea2-turbo` | No | 8 | 2× |
| Kroma Turbo | `kroma` | Sì | 8-12, predefinito 10 | 2× |
| Z-Image-Turbo | `zit` | Sì | 9 | 2× e 4× |
| Juggernaut Z Fast | `juggernaut-z` | Sì | 8 | 2× e 4× |
| ERNIE Image Turbo | `ernie-turbo` | No | 8 | 1,5× e 2× |
| Chroma1-Flash | `chroma` | Sì | 12 | 2× e 4× |
| Boogu Image Turbo | `boogu` | No | 4 | 2× e 4× |

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.

JSONCopia

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

Errori e limiti
| Stato | Tipo e codice | Quando |
| --- | --- | --- |
| 400 | invalid\_request\_error | Manca un campo o un valore non rientra nell'intervallo previsto, oppure il corpo non è JSON valido. Quando il problema riguarda un solo campo, `param` lo indica. |
| 401 | invalid\_request\_error · invalid\_api\_key | La chiave è mancante o errata. |
| 404 | invalid\_request\_error · not\_found | Il percorso o il metodo non esiste. |
| 405 | — | Una richiesta diversa da `POST` è stata inviata a `/mcp`. |
| 413 | invalid\_request\_error · request\_too\_large | Il corpo è più grande di 2 MiB. |
| 429 | rate\_limit\_error · queue\_full | La coda contiene già 8 richieste. Riprova tra poco. |
| 500 | server\_error · generation\_failed · internal\_error | La generazione non è riuscita sul Mac. |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | Il server si sta arrestando, il motore richiede un momento oppure non è attivo alcun modello. Riprova dopo i secondi indicati nell'header `Retry-After`. |

-   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

-   ### Come posso generare immagini con Claude?
    
    Connetti Claude Code o Claude Desktop a Private Diffusion via MCP usando l'indirizzo e la chiave in Details nella scheda API Server dell'app. Poi chiedi a Claude un'immagine. Claude chiama Private Diffusion, che crea l'immagine sul tuo Mac e la restituisce.
    
-   ### È compatibile con l'API immagini di OpenAI?
    
    Sì, per generare immagini. Indirizza un SDK OpenAI all'indirizzo del tuo Mac con la tua chiave e la chiamata di generazione immagini funziona come con OpenAI. Le differenze: le immagini vengono restituite come base64, non c'è modifica né input di immagini e hai campi aggiuntivi come seed e prompt negativo.
    
-   ### Possono usarlo altri dispositivi della mia rete?
    
    Sì. Qualsiasi dispositivo che può raggiungere il tuo Mac può usarlo con la tua chiave. Usa l'indirizzo in Details nella scheda API Server dell'app.
    
-   ### La connessione è crittografata?
    
    No. Il server usa HTTP semplice, quindi usalo su reti affidabili, mantieni privata la chiave e rigenerala se viene divulgata.
    
-   ### Quali modelli funzionano con l'API?
    
    Ogni modello che hai scaricato sul tuo Mac. Ciascuno mantiene le proprie regole per passaggi, prompt negativi e upscaling, elencate nella tabella di questa pagina.
    
-   ### Cosa succede quando arrivano più richieste insieme?
    
    Il tuo Mac genera un'immagine alla volta. Fino a 8 richieste attendono in coda e la successiva riceve un errore 429 finché la coda non avanza. Per impostazione predefinita, gli SDK OpenAI ritentano quell'errore due volte prima di rinunciare.
    
-   ### Funziona su iPhone o iPad?
    
    No. Il server API fa parte di Private Diffusion per Mac. Su iPhone e iPad, generi immagini direttamente nell'app.
    

In questa pagina

1.  [Panoramica](#overview)
2.  [Configurazione](#setup)
3.  [Prima di connetterti](#before-you-connect)
4.  [Esempi](#examples)
5.  [Claude e MCP](#mcp)
6.  [Autenticazione](#authentication)
7.  [Endpoint](#endpoints)
8.  [Modelli](#models)
9.  [Errori e limiti](#errors)
10.  [FAQ](#faq)