API 伺服器 · Mac

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

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

-   僅限 Mac
-   Beta

[![在 App Store 預訂](/app-store/pre-order-badge/zh-TW/pre-order.svg)![在 App Store 預訂](/app-store/pre-order-badge/zh-TW/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

本頁內容

1.  [概覽](#overview)
2.  [設定](#setup)
3.  [連線之前](#before-you-connect)
4.  [範例](#examples)
5.  [Claude 與 MCP](#mcp)
6.  [認證](#authentication)
7.  [端點](#endpoints)
8.  [模型](#models)
9.  [錯誤與限制](#errors)
10.  [常見問題](#faq)

## 由你的 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 伺服器分頁按一下 "啟動 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複製

```
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，並加入少量自有欄位。

請求參數
| 參數 | 值 | 預設 | 備註 |
| --- | --- | --- | --- |
| `prompt` | string | 必填 | 要繪畫的內容。不可空白。 |
| `model` | string | 使用中模型 | 下表所列的模型 ID。未知、未下載或此 Mac 不支援的 ID 會退回至使用中的模型，而回應中的 `model` 會標明實際執行的模型。 |
| `n` | 1–4 | `1` | 影像數量。每張使用下一個種子。 |
| `size` | "auto" | "WxH" | `"auto"` | 會先按形狀、再按面積，套用至模型支援的最接近尺寸。`"auto"` 會在模型允許時選擇 1024×1024。超大尺寸需要記憶體更多的 Mac。 |
| `quality` | "auto" | "low" | "medium" | "high" | `"auto"` | 只有 `"high"` 會改變結果，以速度換取細節。 |
| `output_format` | "png" | "jpeg" | `"png"` | 影像檔案格式。 |
| `output_compression` | 0–100 | `100` | JPEG 輸出的壓縮率。100 壓縮最少。 |
| `seed` | integer | 隨機 | 設定為重複某個結果。 |
| `negative_prompt` | string | 無 | 要從影像中排除的內容。僅部分模型支援；其餘會回傳 400。 |
| `steps` | integer | 模型預設值 | 必須在模型範圍內。固定步數的模型只接受自己的數值。 |
| `upscale` | 1.5 | 2 | 4 | 無 | 在影像生成後放大。模型必須提供該倍率，且其放大模型已下載，否則請求會回傳 400。在記憶體較少的 Mac 上，4 會變成 2。 |
| `stream` | boolean | `false` | 以伺服器傳送事件回傳結果，可選擇包含預覽。 |
| `partial_images` | 0–3 | `0` | 在最終影像前要串流多少預覽。僅與 `stream` 搭配使用。 |

#### 回應

影像會以 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_image` | `type, b64_json, partial_image_index, created_at, watermarked`
影像形成期間的預覽。每張影像的索引都會從 0 重新開始。

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

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

 |
| `error` | `error`

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

 |

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

### `GET /v1/models`

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

## 哪些模型可透過 API 使用

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

哪些模型可透過 API 使用
| 模型 | Id | 負面提示詞 | 步數 | 放大 |
| --- | --- | --- | --- | --- |
| Anima | `anima` | 否 | 8-12，預設 8 | 2× |
| Flux.2 Klein 4B | `klein` | 是 | 4 | 1.5×及2× |
| Mage Flow Turbo | `mage-flow-turbo` | 否 | 4 | 1.5×及2× |
| Krea 2 Turbo | `krea2-turbo` | 否 | 8 | 2× |
| Kroma Turbo | `kroma` | 是 | 8-12，預設 10 | 2× |
| Z-Image-Turbo | `zit` | 是 | 9 | 2×及4× |
| Juggernaut Z Fast | `juggernaut-z` | 是 | 8 | 2×及4× |
| ERNIE Image Turbo | `ernie-turbo` | 否 | 8 | 1.5×及2× |
| Chroma1-Flash | `chroma` | 是 | 12 | 2×及4× |
| Boogu Image Turbo | `boogu` | 否 | 4 | 2×及4× |

Krea 2 Turbo 透過 API 執行時一律使用 8 步，即使 Studio 設為較快的 4 步模式亦一樣。

尺寸和放大倍率取決於 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
  }
}
```

錯誤與限制
| 狀態 | 類型與代碼 | 發生時機 |
| --- | --- | --- |
| 400 | invalid\_request\_error | 某個欄位缺失或超出範圍，或者 body 唔係有效嘅 JSON。當某個欄位出錯時，`param` 會指出係邊一個欄位。 |
| 401 | invalid\_request\_error · invalid\_api\_key | 金鑰缺失或錯誤。 |
| 404 | invalid\_request\_error · not\_found | 路徑或方法不存在。 |
| 405 | — | 非 `POST` 的請求被傳送到 `/mcp`。 |
| 413 | invalid\_request\_error · request\_too\_large | 內文大於 2 MiB。 |
| 429 | rate\_limit\_error · queue\_full | 佇列中已有 8 個請求。請稍後再試。 |
| 500 | server\_error · generation\_failed · internal\_error | 在 Mac 上生成失敗。 |
| 503 | server\_error · server\_stopping · runtime\_unavailable · model\_unavailable | 伺服器正在停止、引擎需要一點時間，或沒有使用中的模型。請在 `Retry-After` 所載的秒數後重試。 |

-   請求內文上限為 2 MiB。
-   每個請求可生成一至 4 張影像。
-   一次生成一張影像，最多可有 8 個請求等候。
-   每個 503 回應都會帶有 `Retry-After`，值為 10 秒。

## 常見問題

-   ### 如何使用 Claude 生成影像？
    
    使用 App 的「API Server」分頁「Details」中的地址和金鑰，透過 MCP 將 Claude Code 或 Claude Desktop 連接到 Private Diffusion。然後向 Claude 要求圖片。Claude 會呼叫 Private Diffusion，在你的 Mac 上生成影像並回傳。
    
-   ### 是否相容於 OpenAI 影像 API？
    
    是，可用於生成影像。將 OpenAI SDK 指向你 Mac 的地址並附上金鑰，影像生成呼叫的方式與 OpenAI 相同。差異在於：影像以 base64 回傳、不支援編輯或影像輸入，而且你會得到種子和負面提示詞等額外欄位。
    
-   ### 網絡上的其他裝置可以使用嗎？
    
    可以。任何能連上你 Mac 的裝置都可以使用你的金鑰。請使用 App「API Server」分頁中「Details」的地址。
    
-   ### 連線是否加密？
    
    否。伺服器使用純 HTTP，因此請在你信任的網絡上使用，保管好金鑰，如外洩請重新產生。
    
-   ### 哪些模型可透過 API 使用？
    
    你在 Mac 上已下載的所有模型。每個模型對步數、負面提示詞和放大都有各自的規則，詳見本頁表格。
    
-   ### 多個請求同時到達時會怎樣？
    
    你的 Mac 一次只會生成一張圖像。最多有 8 個請求在排隊，在隊伍前進之前，下一個請求會收到 429 錯誤。OpenAI SDK 預設會重試該錯誤兩次，之後才會放棄。
    
-   ### 是否適用於 iPhone 或 iPad？
    
    否。API 伺服器是 Private Diffusion for Mac 的一部分。在 iPhone 和 iPad 上，你可以直接在 App 內生成影像。
    

本頁內容

1.  [概覽](#overview)
2.  [設定](#setup)
3.  [連線之前](#before-you-connect)
4.  [範例](#examples)
5.  [Claude 與 MCP](#mcp)
6.  [認證](#authentication)
7.  [端點](#endpoints)
8.  [模型](#models)
9.  [錯誤與限制](#errors)
10.  [常見問題](#faq)