Serveur API · Mac

# Votre Mac est désormais une API de génération d'images

Démarrez le serveur API dans Private Diffusion et votre Mac répond aux requêtes d'images de Claude, de scripts et de toute app qui utilise l'API d'images OpenAI. Chaque image est créée sur votre Mac, sans relais cloud entre les deux.

-   Mac uniquement
-   Bêta

[![Précommander sur l'App Store](/app-store/pre-order-badge/fr/pre-order.svg)![Précommander sur l'App Store](/app-store/pre-order-badge/fr/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

Sur cette page

1.  [Vue d'ensemble](#overview)
2.  [Configuration](#setup)
3.  [Avant de vous connecter](#before-you-connect)
4.  [Exemples](#examples)
5.  [Claude et MCP](#mcp)
6.  [Authentification](#authentication)
7.  [Points de terminaison](#endpoints)
8.  [Modèles](#models)
9.  [Erreurs et limites](#errors)
10.  [FAQ](#faq)

## API de génération d'images compatible OpenAI, servie depuis votre Mac

Le code y accède via l'API d'images OpenAI, et Claude via MCP. Dans les deux cas, le serveur API exécute les modèles que vous avez déjà téléchargés et renvoie les images finalisées.

### Compatible OpenAI

Pointez un SDK OpenAI vers votre Mac et appelez `images.generate`. La plupart des codes d'image écrits pour OpenAI ne changent qu'à deux endroits : l'URL de base et la clé.

### Claude se connecte via MCP

Ajoutez Private Diffusion à Claude Code ou Claude Desktop, puis demandez une image à Claude. Il appelle l'outil `generate_image`, et votre Mac crée l'image et la renvoie.

### Créé sur votre Mac

Les prompts et les images circulent entre votre client et votre Mac, sans relais cloud. Tout appareil pouvant joindre votre Mac peut lui envoyer des requêtes, et il ne répond qu'à celles qui portent votre clé.

## Configurez-le en trois étapes

1.  1
    
    ### Téléchargez un modèle
    
    Ouvrez Private Diffusion sur votre Mac et téléchargez au moins un modèle. Le serveur génère avec les modèles que vous possédez, et celui qui est actif dans Studio est son modèle par défaut.
    
2.  2
    
    ### Démarrez le serveur API
    
    Cliquez sur Démarrer le serveur API dans l'onglet Serveur API, ou utilisez le menu Serveur (⇧⌘A). Pour le lancer à chaque ouverture de l'app, activez "Démarrer le serveur API au lancement" dans Réglages › Serveur API.
    
3.  3
    
    ### Copiez votre adresse et votre clé
    
    Cliquez sur Details dans l'onglet API Server. Vous y trouverez les adresses de votre Mac, votre clé et des commandes prêtes à l'emploi pour `curl`, Claude Code et Claude Desktop, avec les deux déjà renseignés.
    

## À savoir avant de vous connecter

-   Le serveur utilise HTTP en clair. Votre clé, vos prompts et vos images traversent le réseau sans chiffrement : utilisez-le donc sur des réseaux de confiance et arrêtez-le sur les réseaux Wi-Fi publics.
-   Tout appareil pouvant joindre votre Mac et disposant de la clé peut générer des images.
-   Traitez la clé comme un mot de passe. Si elle fuit, régénérez-la dans Settings › API Server. Les clients qui utilisent l'ancienne clé cessent de fonctionner jusqu'à ce que vous leur donniez la nouvelle.
-   Toute page web à laquelle vous donnez la clé peut appeler le serveur depuis votre navigateur. Collez-la uniquement dans des outils de confiance.
-   Lorsque "Démarrer le serveur API au lancement" est activé, votre Mac sert sur chaque réseau auquel il se connecte. Désactivez-le sur un ordinateur portable qui se déplace.
-   Pendant que le serveur est actif, Studio se met en pause, votre Mac reste éveillé, et le changement ou la suppression de modèles attend que vous l'arrêtiez.
-   Les images créées via l'API arrivent dans votre galerie. Activez Incognito Mode, ou désactivez Save API images to gallery, pour les en exclure.
-   Votre Mac crée une image à la fois. Jusqu'à 8 requêtes attendent leur tour, et la suivante reçoit une erreur `queue_full`.

## Générez des images depuis `curl`, Python et JavaScript

Chaque exemple crée une image et l'enregistre dans un fichier. Placez votre clé dans une variable d'environnement nommée `PD_API_KEY`, et remplacez `your-mac.local` par l'adresse de votre Mac indiquée dans Details de l'onglet API Server.

8963 est le port par défaut. Si vous l'avez modifié dans Settings › API Server, utilisez le vôtre.

### curl

Envoie le prompt et décode l'image renvoyée avec `jq`.

curlCopier

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

Utilise le package officiel `openai`. Les champs que l'API OpenAI ne définit pas, tels que `seed`, vont dans `extra_body`. Par défaut, le SDK réessaie deux fois lorsqu'une file est pleine, puis renvoie l'erreur.

PythonCopier

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

S'exécute dans Node.js avec le package `openai`, qui envoie les champs supplémentaires tels que `seed` tels quels. Ne l'exécutez jamais dans une page web, où n'importe qui pourrait lire la clé.

JavaScriptCopier

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

## Génération d'images avec Claude via MCP : Claude Code et Claude Desktop

Private Diffusion utilise le Model Context Protocol à l'adresse `/mcp`. Connectez Claude une fois, puis demandez des images en langage naturel.

### Claude Code

Une fois `PD_API_KEY` défini comme ci-dessus, exécutez cette commande une seule fois dans votre terminal pour ajouter le serveur à Claude Code.

TerminalCopier

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

N'ajoutez pas `--scope project`. Cela écrit votre clé dans un fichier `.mcp.json` destiné à être partagé.

### Claude Desktop

Claude Desktop accède au serveur via `mcp-remote`, un petit pont qui s'exécute sur Node.js. Dans Claude Desktop, ouvrez Settings › Developer › Edit Config, ajoutez cette entrée, remplacez `pd-your-key` par votre clé, puis redémarrez Claude.

claude\_desktop\_config.jsonCopier

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

Nécessite Node.js. La version du pont est épinglée.

### Outils MCP

Outils MCP
| Outil | Ce qu'il fait |
| --- | --- |
| `generate_image` | Crée une à 4 images à partir d'un prompt. Accepte les champs HTTP sauf `quality` et le streaming, et renvoie `jpeg` avec une compression réglée sur 85, sauf si vous demandez du PNG. Un modèle explicitement choisi mais non prêt provoque une erreur, sans solution de repli. |
| `list_models` | Liste les modèles prêts sur ce Mac, avec les tailles, étapes et facteurs d'agrandissement que chacun accepte ici. |
| `get_image_chunk` | Utilisé par les clients MCP qui affichent des images en taille réelle. Vous ne l'appelez jamais vous-même. |

## Authentification

Chaque requête vers `/v1/*` et `/mcp` porte votre clé dans l'en-tête `Authorization: Bearer pd-…`. L'app crée la clé au premier démarrage du serveur. Affichez-la ou régénérez-la dans Settings › API Server.

Une clé absente ou incorrecte renvoie 401 avec le code `invalid_api_key`.

## Points de terminaison : `/v1/images/generations`, `/v1/models` et `/mcp`

### `POST /v1/images/generations`

Génère des images à partir d'un prompt texte. Les requêtes et réponses suivent l'API d'images OpenAI, avec quelques champs propres à l'app.

Paramètres de requête
| Paramètre | Valeurs | Par défaut | Notes |
| --- | --- | --- | --- |
| `prompt` | string | Obligatoire | Ce qu'il faut dessiner. Ne doit pas être vide. |
| `model` | string | Modèle actif | Un identifiant de modèle du tableau ci-dessous. Un identifiant inconnu, non téléchargé ou non pris en charge sur ce Mac bascule vers le modèle actif, et le `model` de la réponse indique celui qui a été exécuté. |
| `n` | 1–4 | `1` | Combien d'images. Chacune utilise la seed suivante. |
| `size` | "auto" | "WxH" | `"auto"` | S'ajuste à la taille prise en charge la plus proche par le modèle, d'abord selon la forme puis selon la surface. `"auto"` choisit 1024×1024 lorsque le modèle le permet. Les très grandes tailles nécessitent un Mac avec davantage de mémoire. |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | Seul `"high"` modifie le résultat, en échangeant de la vitesse contre des détails. |
| `output_format` | "png" | "jpeg" | `"png"` | Le format de fichier de l'image. |
| `output_compression` | 0–100 | `100` | Compression pour la sortie JPEG. 100 compresse le moins. |
| `seed` | integer | Aléatoire | Définissez-la pour reproduire un résultat. |
| `negative_prompt` | string | Aucun | Ce qu'il faut exclure de l'image. Certains modèles seulement ; les autres renvoient 400. |
| `steps` | integer | Valeur par défaut du modèle | Doit être dans la plage du modèle. Les modèles à nombre d'étapes fixe n'acceptent que leur propre valeur. |
| `upscale` | 1.5 | 2 | 4 | Aucun | Agrandit l'image après sa création. Le modèle doit proposer ce facteur et son agrandisseur doit être téléchargé, sinon la requête renvoie 400. Sur les Mac avec moins de mémoire, 4 devient 2. |
| `stream` | boolean | `false` | Envoie le résultat sous forme d'événements envoyés par le serveur, avec des aperçus facultatifs. |
| `partial_images` | 0–3 | `0` | Combien d'aperçus diffuser avant l'image finale. Utilisé uniquement avec `stream`. |

#### Réponse

Les images reviennent en base64 dans `b64_json`, jamais sous forme d'URL, chacune avec sa `seed` et l'indication d'un filigrane. `model` indique le modèle utilisé.

JSONCopier

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

### Images partielles en streaming

Définissez `stream` sur true et le serveur répond avec des événements envoyés par le serveur. Chaque trame indique son événement et contient un objet JSON.

Images partielles en streaming
| Événement | Données |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Un aperçu pendant la création de l'image. L'index recommence à 0 pour chaque image.

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

L'image finalisée avec sa seed. Une par image lorsque vous en demandez plusieurs.

 |
| `error` | `error`

Un échec est survenu après l'ouverture du flux. Les erreurs antérieures arrivent sous forme de réponse JSON normale.

 |

Le flux se ferme après la dernière image. Il n'y a pas d'événement done distinct.

### `GET /v1/models`

Liste les modèles téléchargés, prêts et pris en charge sur ce Mac. Envoyez l'un de leurs identifiants comme `model`.

## Quels modèles fonctionnent via l'API

Chaque modèle Private Diffusion fonctionne via l'API une fois téléchargé, si votre Mac le prend en charge. Envoyez l'identifiant de la deuxième colonne comme `model`.

Quels modèles fonctionnent via l'API
| Modèle | Identifiant | Prompt négatif | Étapes | Agrandissement |
| --- | --- | --- | --- | --- |
| Anima | `anima` | Non | 8-12, valeur par défaut : 8 | 2× |
| Flux.2 Klein 4B | `klein` | Oui | 4 | 1,5×, 2× |
| Mage Flow Turbo | `mage-flow-turbo` | Non | 4 | 1,5×, 2× |
| Krea 2 Turbo | `krea2-turbo` | Non | 8 | 2× |
| Kroma Turbo | `kroma` | Oui | 8-12, valeur par défaut : 10 | 2× |
| Z-Image-Turbo | `zit` | Oui | 9 | 2×, 4× |
| Juggernaut Z Fast | `juggernaut-z` | Oui | 8 | 2×, 4× |
| ERNIE Image Turbo | `ernie-turbo` | Non | 8 | 1,5×, 2× |
| Chroma1-Flash | `chroma` | Oui | 12 | 2×, 4× |
| Boogu Image Turbo | `boogu` | Non | 4 | 2×, 4× |

Krea 2 Turbo effectue toujours 8 étapes via l'API, même lorsque Studio est réglé sur son mode plus rapide à 4 étapes.

Les tailles et facteurs d'agrandissement dépendent de la mémoire de votre Mac. L'outil MCP `list_models` indique ce que votre Mac accepte.

## Erreurs et limites

Les erreurs suivent le format OpenAI : un objet JSON avec un message, un type, le paramètre en cause et un code.

JSONCopier

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

Erreurs et limites
| Statut | Type et code | Quand |
| --- | --- | --- |
| 400 | invalid\_request\_error | Un champ est manquant ou hors plage, ou le corps n'est pas du JSON valide. Lorsqu'un seul champ est en cause, `param` l'indique. |
| 401 | invalid\_request\_error · invalid\_api\_key | La clé est absente ou incorrecte. |
| 404 | invalid\_request\_error · not\_found | Le chemin ou la méthode n'existe pas. |
| 405 | — | Une requête autre que `POST` a été envoyée à `/mcp`. |
| 413 | invalid\_request\_error · request\_too\_large | Le corps dépasse 2 MiB. |
| 429 | rate\_limit\_error · queue\_full | La file contient déjà 8 requêtes. Réessayez dans un instant. |
| 500 | server\_error · generation\_failed · internal\_error | La génération a échoué sur le Mac. |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | Le serveur s'arrête, le moteur a besoin d'un instant, ou aucun modèle n'est actif. Réessayez après le nombre de secondes indiqué dans `Retry-After`. |

-   Corps de requête jusqu'à 2 MiB.
-   De une à 4 images par requête.
-   Une image à la fois, avec jusqu'à 8 en attente.
-   Chaque 503 inclut `Retry-After` de 10 secondes.

## FAQ

-   ### Comment générer des images avec Claude ?
    
    Connectez Claude Code ou Claude Desktop à Private Diffusion via MCP avec l'adresse et la clé de Details dans l'onglet API Server de l'app. Demandez ensuite une image à Claude. Claude appelle Private Diffusion, qui crée l'image sur votre Mac et la renvoie.
    
-   ### Est-ce compatible avec l'API d'images OpenAI ?
    
    Oui, pour générer des images. Pointez un SDK OpenAI vers l'adresse de votre Mac avec votre clé, et l'appel de génération d'images fonctionne comme avec OpenAI. Les différences : les images reviennent en base64, il n'y a pas de modification ni d'entrée d'image, et vous obtenez des champs supplémentaires tels qu'une seed et un prompt négatif.
    
-   ### D'autres appareils de mon réseau peuvent-ils l'utiliser ?
    
    Oui. Tout appareil pouvant joindre votre Mac peut l'utiliser avec votre clé. Utilisez l'adresse de Details dans l'onglet API Server de l'app.
    
-   ### La connexion est-elle chiffrée ?
    
    Non. Le serveur utilise HTTP en clair, alors utilisez-le sur des réseaux de confiance, gardez la clé privée et régénérez-la si elle fuit.
    
-   ### Quels modèles fonctionnent via l'API ?
    
    Tous les modèles que vous avez téléchargés sur votre Mac. Chacun conserve ses propres règles pour les étapes, les prompts négatifs et l'agrandissement, indiquées dans le tableau de cette page.
    
-   ### Que se passe-t-il quand plusieurs requêtes arrivent en même temps ?
    
    Votre Mac crée une image à la fois. Jusqu'à 8 requêtes attendent dans la file, et la suivante reçoit une erreur 429 jusqu'à ce que la file avance. Par défaut, les SDK OpenAI réessaient deux fois cette erreur avant d'abandonner.
    
-   ### Est-ce que cela fonctionne sur iPhone ou iPad ?
    
    Non. Le serveur API fait partie de Private Diffusion pour Mac. Sur iPhone et iPad, vous générez les images directement dans l'app.
    

Sur cette page

1.  [Vue d'ensemble](#overview)
2.  [Configuration](#setup)
3.  [Avant de vous connecter](#before-you-connect)
4.  [Exemples](#examples)
5.  [Claude et MCP](#mcp)
6.  [Authentification](#authentication)
7.  [Points de terminaison](#endpoints)
8.  [Modèles](#models)
9.  [Erreurs et limites](#errors)
10.  [FAQ](#faq)