你的 Mac 現在就是一個影像生成 API

三個步驟完成設定

1. 1

   下載模型

   在 Mac 上開啟 Private Diffusion 並下載至少一個模型。伺服器會使用你擁有的模型來生成，而在 Studio 中啟用的模型就是它的預設模型。

2. 2

   啟動 API 伺服器

   在 API 伺服器分頁中按一下啟動 API 伺服器，或使用伺服器選單 (⇧⌘A)。若要在每次開啟 App 時提供服務，請在設定 › API 伺服器中開啟 "啟動時啟動 API 伺服器"。

3. 3

   複製你的位址和金鑰

   在「API Server」分頁中按一下「Details」。它會列出你 Mac 的位址、你的金鑰，以及已填入位址與金鑰的 curl、Claude Code 和 Claude Desktop 現成指令。

連線前須知

• 伺服器使用純 HTTP。你的金鑰、提示詞和影像會以未加密的方式在網路上傳輸，因此請在信任的網路上執行，並在公用 Wi-Fi 上停止它。
• 任何能連上你的 Mac 且持有金鑰的裝置都能生成影像。
• 請將金鑰視為密碼。若金鑰外洩，請在「Settings › API Server」中重新產生。使用舊金鑰的用戶端會停止運作，直到你提供新金鑰為止。
• 任何你提供金鑰的網頁都能從你的瀏覽器呼叫伺服器。只將金鑰貼到你信任的工具中。
• 開啟 "啟動時啟動 API 伺服器" 後，你的 Mac 會在它加入的每個網路上提供服務。請在會帶出門的筆記型電腦上將它關閉。
• 伺服器執行期間，Studio 會暫停，你的 Mac 會保持喚醒，而切換或刪除模型的操作會等到你停止伺服器後才進行。
• 透過 API 製作的影像會進入你的圖庫。開啟「Incognito Mode」，或關閉「Save API images to gallery」，即可避免它們出現在圖庫中。
• 你的 Mac 一次只會製作一張影像。最多 8 個請求會排隊等候，超過此數量時，下一個請求會收到 queue_full 錯誤。

從 curl、Python 和 JavaScript 生成影像

每個範例都會製作一張圖片並儲存為檔案。請將金鑰放入名為 PD_API_KEY 的環境變數中，並將 your-mac.local 替換為你在「API Server」分頁「Details」中看到的 Mac 位址。

8963 是預設連接埠。如果你在「Settings › API Server」中更改過，請使用你自己的連接埠。

curl

傳送提示詞，並使用 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)

使用官方 openai 套件。OpenAI API 未定義的欄位，例如 seed，會放入 extra_body。SDK 預設會對整個佇列重試兩次，然後才拋出錯誤。

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)

使用 openai 套件在 Node.js 中執行，該套件會原樣傳送 seed 等額外欄位。切勿在網頁中執行此程式碼，否則任何人都可能讀取金鑰。

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

透過 MCP 使用 Claude 生成影像：Claude Code 與 Claude Desktop

Private Diffusion 在 /mcp 提供 Model Context Protocol。連接 Claude 一次，之後就能用自然語言要求影像。

Claude Code

在依上述方式設定 PD_API_KEY 後，請在終端機中執行此指令一次，將伺服器加入 Claude Code。

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

請勿加上 --scope project。它會把你的金鑰寫進一個本來就要分享的 .mcp.json 檔案裡。

Claude Desktop

Claude Desktop 透過 mcp-remote（一個在 Node.js 上執行的小型橋接程式）連上伺服器。在 Claude Desktop 中開啟「Settings › Developer › Edit Config」，加入此設定項目，將 pd-your-key 替換為你的金鑰，然後重新啟動 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"
      }
    }
  }
}

需要 Node.js。橋接程式版本已固定。

MCP 工具

驗證

每個傳送至 /v1/* 和 /mcp 的請求都會在 Authorization: Bearer pd-… 標頭中帶有你的金鑰。App 會在伺服器首次啟動時建立金鑰。你可以在「Settings › API Server」中顯示或重新產生金鑰。

金鑰遺失或錯誤會回傳 401，並附上代碼 invalid_api_key。

端點：/v1/images/generations、/v1/models 與 /mcp

POST /v1/images/generations

從文字提示詞生成影像。請求與回應遵循 OpenAI 影像 API，並加入一些自有欄位。

回應

影像會以 b64_json 中的 base64 格式回傳，永遠不會是 URL；每張影像都包含其 seed 以及是否帶有浮水印。model 會標明執行的模型。

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

串流部分影像

將 stream 設為 true，伺服器便會以伺服器傳送事件回應。每個影格都會標明其事件名稱，並攜帶一個 JSON 物件。

串流會在最後一張影像後關閉。沒有另外的完成事件。

GET /v1/models

列出此 Mac 上已下載、已就緒且受支援的模型。請將其中一個 ID 作為 model 傳送。

哪些模型可透過 API 使用

每個 Private Diffusion 模型在下載完成且你的 Mac 支援後，都可以透過 API 使用。請將第二欄的 id 作為 model 傳送。

Krea 2 Turbo 透過 API 一律執行 8 個步驟，即使 Studio 設定為更快的 4 步驟模式亦然。

尺寸和放大倍率取決於 Mac 的記憶體。list_models MCP 工具會回報你的 Mac 可接受的值。

錯誤與限制

錯誤遵循 OpenAI 的格式：包含訊息、類型、出錯參數和代碼的 JSON 物件。

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

• 請求主體最大為 2 MiB。
• 每個請求 1 至 4 張影像。
• 一次一張影像，最多 8 個請求等候。
• 每個 503 回應都會附上 Retry-After，值為 10 秒。

常見問題