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)

## 與 OpenAI 相容的影像生成 API，由你的 Mac 提供服務

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

### 與 OpenAI 相容

將 OpenAI SDK 指向你的 Mac，並呼叫 `images.generate`。大部分為 OpenAI 撰寫的圖片程式碼只需在兩個地方修改：基礎 URL 和金鑰。

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

使用 `openai` 套件在 Node.js 中執行，該套件會原樣傳送 `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`，除非你要求 PNG，否則壓縮設定為 85。明確指定的模型若尚未就緒會是錯誤，而不會退回使用其他模型。 |
| `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。若 ID 未知、尚未下載，或此 Mac 不支援，則會退回使用目前啟用的模型，而回應的 `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` 一起使用。 |

#### 回應

影像會以 `b64_json` 中的 base64 格式回傳，永遠不會是 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 | 某個欄位遺漏或超出範圍，或者主體不是有效的 JSON。當某個欄位有問題時，`param` 會指出它。 |
| 401 | invalid\_request\_error · invalid\_api\_key | 金鑰遺失或錯誤。 |
| 404 | invalid\_request\_error · not\_found | 路徑或方法不存在。 |
| 405 | — | 傳送至 `/mcp` 的請求不是 `POST`。 |
| 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。
-   每個請求 1 至 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 伺服器是 Mac 版 Private Diffusion 的一部分。在 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)