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

三步完成设置

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 -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 会对整个队列重试两次，然后抛出错误。

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",
        "[email protected]",
        "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 工具

认证

发送到 /v1/* 和 /mcp 的每个请求都会在 Authorization: Bearer pd-… 标头中携带你的密钥。应用会在服务器首次启动时创建该密钥。你可以在 "Settings › API Server" 中查看或重新生成它。

缺少密钥或密钥错误会返回 401，并带有代码 invalid_api_key。

端点：/v1/images/generations、/v1/models 和 /mcp

POST /v1/images/generations

根据文本提示生成图像。请求和响应遵循 OpenAI 图像 API，并带有一些自有字段。

响应

图像以 base64 形式在 b64_json 中返回，绝不会是 URL，每张图像都带有其 seed 以及是否包含水印。model 会标明实际运行的模型。

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

流式传输部分图像

将 stream 设置为 true，服务器就会以服务器发送事件进行响应。每个帧都会命名其事件，并携带一个 JSON 对象。

流在最后一张图像之后关闭。没有单独的完成事件。

GET /v1/models

列出此 Mac 上已下载、就绪且受支持的模型。将其中一个 ID 作为 model 发送。

哪些模型可通过 API 使用

每个 Private Diffusion 模型在下载完成并且你的 Mac 支持后，均可通过 API 使用。请将第二列中的 id 作为 model 发送。

Krea 2 Turbo 在通过 API 时始终运行 8 步，即使 Studio 设置为更快的 4 步模式。

大小和放大倍数取决于你的 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
  }
}

• 请求体最大为 2 MiB。
• 每个请求 1 到 4 张图像。
• 一次生成一张图像，最多 8 个排队等待。
• 每个 503 响应都带有 Retry-After，值为 10 秒。

常见问题