API 服务器 · Mac

# 你的 Mac 现在是一个图像生成 API

在 Private Diffusion 中启动 API 服务器，你的 Mac 就会响应来自 Claude、脚本以及任何使用 OpenAI 图像 API 的应用的图像请求。每张图像都在你的 Mac 上生成，中间没有云端中转。

-   仅限 Mac
-   Beta

[![在 App Store 预订](/app-store/pre-order-badge/zh-CN/pre-order.svg)![在 App Store 预订](/app-store/pre-order-badge/zh-CN/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)。若要在每次打开应用时自动提供服务，请在 设置 › 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`，除非你要求 PNG，否则压缩设置为 85。明确指定的模型若尚未就绪，则返回错误，而不会回退。 |
| `list_models` | 列出此 Mac 上已就绪的模型，以及每个模型在此处接受的大小、步数和放大倍数。 |
| `get_image_chunk` | 供显示全尺寸图像的 MCP 客户端使用。你不需要自己调用它。 |

## 认证

发送到 `/v1/*` 和 `/mcp` 的每个请求都会在 `Authorization: Bearer pd-…` 标头中携带你的密钥。应用会在服务器首次启动时创建该密钥。你可以在 "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 | 某个字段缺失或超出范围，或者请求体不是有效的 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 生成图像？
    
    使用应用的 "API Server" 标签页 "Details" 中的地址和密钥，通过 MCP 将 Claude Code 或 Claude Desktop 连接到 Private Diffusion。然后让 Claude 生成一张图片。Claude 会调用 Private Diffusion，在你的 Mac 上生成图像并返回。
    
-   ### 它是否兼容 OpenAI 图像 API？
    
    是的，可用于生成图像。将 OpenAI SDK 指向你的 Mac 地址并使用你的密钥，图像生成调用就可以像在 OpenAI 中一样工作。区别在于：图像以 base64 形式返回，不支持编辑或图像输入，并且你会获得种子和负面提示词等额外字段。
    
-   ### 我网络中的其他设备可以使用它吗？
    
    可以。任何能访问你的 Mac 的设备都可以使用你的密钥来使用它。请使用应用 "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)