API 服务器 · Mac
你的 Mac 现在是一台图像生成服务器
在 Private Diffusion 中启动 API 服务器,你的 Mac 就会响应来自 Claude、脚本以及任何使用 OpenAI 图像 API 的应用的图像请求。每张图像都在你的 Mac 上生成,中间没有云端中转。
- 仅限 Mac
- Beta
用你的 AI 智能体完成设置
将这段提示词粘贴到 Claude Code 或任意编程智能体中。该智能体会检查你 Mac 上的 API 服务器是否在运行,然后设置 MCP 或在你自己的代码中添加脚本。
Download https://privatediffusion.ai/agent-setup.md with curl, read it in full, and follow it to connect me to the Private Diffusion API server on my Mac.
兼容 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
下载模型
在你的 Mac 上打开 Private Diffusion,并至少下载一个模型。服务器会使用你已有的模型生成图像,Studio 中当前选中的模型即为默认模型。
- 2
启动 API 服务器
在“API Server”标签页中点击“Start API Server”,或使用“Server”菜单(⇧⌘A)。若要在每次打开应用时自动提供服务,请在“Settings › API Server”中开启“Start the API server at launch”。
- 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 -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.pngPython (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",
"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 工具
| 工具 | 作用 |
|---|---|
generate_image | 根据提示词生成 1 到 4 张图像。接受除 quality 和流式传输之外的 HTTP 字段。除非你要求 PNG,否则返回 jpeg 格式,压缩设置为 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" 会改变结果,用速度换取细节。它对 Nanosaur 2 或 MOSS-Image 没有影响。 |
output_format | "png" | "jpeg" | "png" | 图像文件格式。 |
output_compression | 0–100 | 100 | JPEG 输出的压缩率。100 表示压缩最少。 |
seed | integer | 随机 | 设置此参数可复现结果。 |
negative_prompt | string | 无 | 希望从图像中排除的内容。仅部分模型支持;其余模型会返回 400。MOSS-Image 接受该参数,但仅在 Quality 模式下才会读取。 |
steps | integer | 模型默认值 | 必须位于模型的范围内。固定步数的模型只接受其自身规定的值。MOSS-Image 只接受 50,该值会运行 Quality 模式;若省略 steps 参数,则使用其 4-step 模式,但需要安装适配器。 |
upscale | 1.5 | 2 | 4 | 无 | 在图像生成后对其进行放大。模型必须支持该倍率,并且其放大功能必须已下载,否则请求会返回 400。Nanosaur 2 没有放大功能。在内存较小的 Mac 上,4 倍会变成 2 倍。 |
stream | boolean | false | 以服务器发送事件的形式发送结果,除 Nanosaur 2 外的所有模型都可以选择发送预览。 |
partial_images | 0–3 | 0 | 在最终图像之前要流式发送多少预览。仅与 stream 一起使用。Nanosaur 2 只发送最终图像。 |
响应
图像以 base64 形式在 b64_json 中返回,不会以 URL 形式返回;每张图像都附带其 seed,并注明是否带有水印。model 会标明实际运行的模型。
{
"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 发送。
| 模型 | ID | 负面提示词 | 步数 | 放大 |
|---|---|---|---|---|
| Anima | anima | 否 | 8-12,默认 8 | 2× |
| Flux.2 Klein 4B | klein | 是 | 4 | 1.5×、2× |
| Nanosaur 2 | nanosaur2 | 否 | 4 | 否 |
| Mage Flow Turbo | mage-flow-turbo | 否 | 4 | 1.5×、2× |
| MOSS-Image | moss-image | 是 | 安装适配器后默认 4(XL 尺寸下为 6),Quality 模式下为 50。 | 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 中如何设置。
当你省略 steps 参数时,如果已安装适配器,MOSS-Image 会运行其 4-step 模式(XL 尺寸下为六步);如果未安装,则运行 Quality 模式。发送 steps: 50 会运行 Quality 模式,这需要更长时间,并且是唯一读取 negative_prompt 的模式;任何其他 steps 值都会返回 400。
尺寸和放大倍数取决于你的 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
}
}| 状态 | 类型和代码 | 触发条件 |
|---|---|---|
| 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 秒。
常见问题
使用应用“API Server”标签页“Details”中的地址和密钥,通过 MCP 将 Claude Code 或 Claude Desktop 连接到 Private Diffusion。然后让 Claude 生成一张图片。Claude 会调用 Private Diffusion,在你的 Mac 上生成图像并返回。
是的,可用于生成图像。将 OpenAI SDK 指向你的 Mac 地址并使用你的密钥,图像生成调用就可以像在 OpenAI 中一样工作。区别在于:图像以 base64 形式返回,不支持编辑或图像输入,并且你会获得种子和负面提示词等额外字段。
可以。任何能访问你的 Mac 的设备,只要持有你的密钥,就能使用它。请使用应用“API Server”标签页“Details”中的地址。
不加密。服务器使用纯 HTTP,因此请在你信任的网络上使用,妥善保管密钥,并在密钥泄露时重新生成。
你在 Mac 上下载的每个模型都可以。每个模型对步数、负面提示词和放大都有各自的规则,请参见本页表格。
你的 Mac 一次生成一张图像。最多 8 个请求排队等待,队列腾出位置之前,再来的请求会收到 429 错误。OpenAI SDK 默认会对该错误重试两次,之后才放弃。
不能。API 服务器是 Mac 版 Private Diffusion 的一部分。在 iPhone 和 iPad 上,你可以直接在 App 中生成图像。