你的 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)

在 Node.js 中以 openai 套件執行，它會原樣傳送 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，並加入少量自有欄位。

回應

影像會以 base64 形式放在 b64_json 回傳，絕非 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。
• 每個請求可生成一至 4 張影像。
• 一次生成一張影像，最多可有 8 個請求等候。
• 每個 503 回應都會帶有 Retry-After，值為 10 秒。

常見問題