跳至內容

API 伺服器 · Mac

你的 Mac 現在是一部影像生成伺服器

在 Private Diffusion 啟動 API 伺服器,你的 Mac 就會回應來自 Claude、指令碼及任何支援 OpenAI 影像 API 的 App 所發出的影像請求。每張影像都在你的 Mac 上生成,中間沒有任何雲端中轉。

  • 僅限 Mac
  • Beta

用你的 AI 代理設定

將此提示詞貼到 Claude Code 或任何編碼代理程式。代理程式會檢查你 Mac 上的 API 伺服器是否正在運行,然後在你的程式碼中設定 MCP 或腳本。

由你的 Mac 提供的 OpenAI 相容影像生成 API

程式碼可透過 OpenAI 影像 API 使用它,Claude 則可透過 MCP 使用。無論哪種方式,API 伺服器都會執行你已下載的模型,並回傳完成的影像。

OpenAI 相容

將 OpenAI SDK 指向你的 Mac,然後呼叫 images.generate。大部分為 OpenAI 而寫的圖像程式碼只需改兩處:base URL 和 key。

Claude 透過 MCP 連線

將 Private Diffusion 加到 Claude Code 或 Claude Desktop,然後向 Claude 要求圖片。它會呼叫 generate_image 工具,你的 Mac 就會生成影像並回傳。

在你的 Mac 上生成

提示詞和影像只會在你的用戶端與 Mac 之間傳輸,沒有雲端中轉。任何能連上你 Mac 的裝置都可以傳送請求,但伺服器只會回應帶有你的金鑰的請求。

三個步驟完成設定

  1. 1

    下載模型

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

  2. 2

    啟動 API 伺服器

    在 API Server 分頁按一下 "Start API Server",或者使用 Server 選單(⇧⌘A)。要在每次開啟 app 時都提供服務,請在 Settings › API Server 開啟 "Start the API server at launch"。

  3. 3

    複製你的地址和金鑰

    在「API Server」分頁按一下「Details」。裡面會列出你 Mac 的地址、你的金鑰,以及已填入這些資料的 curl、Claude Code 和 Claude Desktop 現成指令。

連線前須知

  • 伺服器使用純 HTTP 通訊。你的金鑰、提示詞和影像在網絡上均未加密傳輸,因此請只在你信任的網絡上執行,並在公共 Wi-Fi 上停用。
  • 任何能連上你 Mac 且持有金鑰的裝置都可以生成影像。
  • 將金鑰視為密碼。如果外洩,請在「Settings › API Server」重新產生。使用舊金鑰的用戶端會停止運作,直到你提供新金鑰為止。
  • 任何你提供金鑰的網頁都可以從瀏覽器呼叫伺服器。請只貼到你可信賴的工具。
  • 開啟 "Start the API server at launch" 之後,你的 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
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 預設會將整個佇列重試兩次,然後引發錯誤。

Python
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 等額外欄位。切勿在網頁中執行,否則任何人都可能讀取金鑰。

JavaScript
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。

claude_desktop_config.json
{
  "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"
      }
    }
  }
}

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

MCP 工具

MCP 工具
工具用途
generate_image從一個提示生成 1 至 4 張圖像。接受除了 quality 和串流以外的 HTTP 欄位,並傳回 jpeg,壓縮設定為 85,除非你要求 PNG。若明確指定的模型尚未就緒,會視為錯誤,而不會退回其他模型。
list_models列出這台 Mac 上已就緒的模型,以及每個模型在此接受的尺寸、步數和放大倍率。
get_image_chunk供顯示全尺寸影像的 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,並加入少量自有欄位。

請求參數
參數值預設備註
promptstring必填要繪畫的內容。不可空白。
modelstring使用中模型下表所列的模型 ID。未知、未下載或此 Mac 不支援的 ID 會退回至使用中的模型,而回應中的 model 會標明實際執行的模型。
n1–41影像數量。每張使用下一個種子。
size"auto" | "WxH""auto"會先按形狀、再按面積,套用至模型支援的最接近尺寸。"auto" 會在模型允許時選擇 1024×1024。超大尺寸需要記憶體更多的 Mac。
quality"auto" | "low" | "medium" | "high""auto"只有 "high" 會改變結果,以速度換取細節。它對 Nanosaur 2 或 MOSS-Image 沒有影響。
output_format"png" | "jpeg""png"影像檔案格式。
output_compression0–100100JPEG 輸出的壓縮率。100 壓縮最少。
seedinteger隨機設定為重複某個結果。
negative_promptstring無要在圖片中排除的內容。僅部分模型支援;其餘會回傳 400。MOSS-Image 會接受它,但只在 Quality 模式下讀取。
stepsinteger模型預設值必須在模型範圍內。固定步數模型只接受其自身數值。MOSS-Image 只接受 50,該值會執行 Quality;若要使用其 4-step 模式,請省略 steps 參數,且需要安裝其適配器。
upscale1.5 | 2 | 4無在圖片生成後將其放大。模型必須提供該倍率,而且其放大工具必須已下載,否則請求會回傳 400。Nanosaur 2 沒有放大工具。在記憶體較少的 Mac 上,4 倍會變成 2 倍。
streambooleanfalse以伺服器傳送事件形式傳送結果,除 Nanosaur 2 外每個模型都可選擇提供預覽。
partial_images0–30在最終影像前要串流多少個預覽。只會與 stream 一起使用。Nanosaur 2 只會傳送最終影像。

回應

影像會以 base64 形式放在 b64_json 回傳,絕非 URL,每張都附有其 seed 及是否帶有浮水印。model 標明執行的模型。

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

串流部分影像

將 stream 設為 true,伺服器就會以伺服器傳送事件回覆。每個影格都會標明事件名稱,並帶有一個 JSON 物件。

串流部分影像
事件資料
image_generation.partial_imagetype, b64_json, partial_image_index, created_at, watermarked

影像形成期間的預覽。每張影像的索引都會從 0 重新開始。

image_generation.completedtype, b64_json, seed, watermarked, sensitive, created_at

完成影像及其種子。如要求多張,每張各一。

errorerror

串流開始後發生錯誤。之前的錯誤會以一般 JSON 回應回傳。

最後一張影像後串流即關閉。沒有獨立的完成事件。

GET /v1/models

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

哪些模型可透過 API 使用

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

哪些模型可透過 API 使用
模型Id負面提示詞步數放大
Animaanima否8-12,預設 82×
Flux.2 Klein 4Bklein是41.5×及2×
Nanosaur 2nanosaur2否4否
Mage Flow Turbomage-flow-turbo否41.5×及2×
MOSS-Imagemoss-image是使用適配器時預設為 4(XL 為 6),或 50 執行 Quality。1.5×及2×
Krea 2 Turbokrea2-turbo否82×
Kroma Turbokroma是8-12,預設 102×
Z-Image-Turbozit是92×及4×
Juggernaut Z Fastjuggernaut-z是82×及4×
ERNIE Image Turboernie-turbo否81.5×及2×
Chroma1-Flashchroma是122×及4×
Boogu Image Turboboogu否42×及4×

Krea 2 Turbo 透過 API 執行時,無論 Studio 的設定為何,都會在適配器關閉的狀態下固定以 8 步生成。

當你省略 steps 時,若已安裝其適配器,MOSS-Image 會執行其 4-step 模式(XL 尺寸為六步);若未安裝,則執行 Quality。傳送 steps: 50 可執行 Quality,該模式耗時長得多,而且是唯一會讀取 negative_prompt 的模式;任何其他 steps 值都會回傳 400。

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

錯誤與限制

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

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

錯誤與限制
狀態類型與代碼發生時機
400invalid_request_error某個欄位缺失或超出範圍,或者 body 不是有效的 JSON。當某個欄位出錯時,param 會指出是哪一個欄位。
401invalid_request_error · invalid_api_key金鑰缺失或錯誤。
404invalid_request_error · not_found路徑或方法不存在。
405—非 POST 的請求被傳送到 /mcp。
413invalid_request_error · request_too_large內文大於 2 MiB。
429rate_limit_error · queue_full佇列中已有 8 個請求。請稍後再試。
500server_error · generation_failed · internal_error在 Mac 上生成失敗。
503server_error · server_stopping · runtime_unavailable · model_unavailable伺服器正在停止、引擎需要一點時間,或沒有使用中的模型。請在 Retry-After 所載的秒數後重試。
  • 請求內文上限為 2 MiB。
  • 每個請求可生成一至 4 張影像。
  • 一次生成一張影像,最多可有 8 個請求等候。
  • 每個 503 回應都會帶有 Retry-After,值為 10 秒。

常見問題

  • 使用 App 的「API Server」分頁「Details」中的地址和金鑰,透過 MCP 將 Claude Code 或 Claude Desktop 連接到 Private Diffusion。然後向 Claude 要求圖片。Claude 會呼叫 Private Diffusion,在你的 Mac 上生成影像並回傳。

  • 是,可用於生成影像。將 OpenAI SDK 指向你 Mac 的地址並附上金鑰,影像生成呼叫的方式與 OpenAI 相同。差異在於:影像以 base64 回傳、不支援編輯或影像輸入,而且你會得到種子和負面提示詞等額外欄位。

  • 可以。任何能連上你 Mac 的裝置都可以使用你的金鑰。請使用 App「API Server」分頁中「Details」的地址。

  • 否。伺服器使用純 HTTP,因此請在你信任的網絡上使用,保管好金鑰,如外洩請重新產生。

  • 你在 Mac 上已下載的所有模型。每個模型對步數、負面提示詞和放大都有各自的規則,詳見本頁表格。

  • 你的 Mac 一次只會生成一張圖像。最多有 8 個請求在排隊,在隊伍前進之前,下一個請求會收到 429 錯誤。OpenAI SDK 預設會重試該錯誤兩次,之後才會放棄。

  • 否。API 伺服器是 Private Diffusion for Mac 的一部分。在 iPhone 和 iPad 上,你可以直接在 App 內生成影像。