Macが画像生成APIに

3ステップでセットアップ

1. 1

   モデルをダウンロード

   MacでPrivate Diffusionを開き、少なくとも1つのモデルをダウンロードします。サーバーは手元のモデルで生成し、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は一度に1枚の画像を生成します。最大8件のリクエストが順番を待ち、その次のリクエストにはqueue_fullエラーが返ります。

curl、Python、JavaScriptから画像を生成

各例では1枚の画像を生成してファイルに保存します。キーを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パッケージを使用します。seedのようにOpenAI APIで定義されていないフィールドは、extra_bodyに指定します。SDKはキューが満杯の場合、デフォルトで2回リトライしてからエラーを送出します。

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などの追加フィールドをそのまま送信します。キーを誰でも読み取れるウェブページでは絶対に実行しないでください。

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は、Node.jsで動く小さなブリッジであるmcp-remoteを通じてサーバーにアクセスします。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で表示または再生成できます。

キーがない、または間違っている場合は、コードinvalid_api_keyを含む401が返ります。

エンドポイント: /v1/images/generations、/v1/models、/mcp

POST /v1/images/generations

テキストプロンプトから画像を生成します。リクエストとレスポンスはOpenAI画像APIに従いますが、独自のフィールドがいくつかあります。

レスポンス

画像はURLではなくb64_json内のbase64として返され、それぞれに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経由で利用できます。2列目のidをmodelとして送信してください。

Krea 2 Turboは、Studioがより高速な4ステップモードに設定されている場合でも、API経由では常に8ステップで実行されます。

サイズとアップスケール倍率は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枚。
• 一度に1枚、最大8件待機。
• すべての503にはRetry-Afterとして10秒が含まれます。

よくある質問