APIサーバー · Mac

# Macが画像生成APIに

Private DiffusionでAPIサーバーを起動すると、MacがClaude、スクリプト、OpenAI画像APIに対応するあらゆるアプリからの画像リクエストに応答します。すべての画像はMac上で生成され、途中にクラウド中継はありません。

-   Macのみ
-   ベータ

[![App Storeで予約注文](/app-store/pre-order-badge/ja/pre-order.svg)![App Storeで予約注文](/app-store/pre-order-badge/ja/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)

## Macから提供するOpenAI互換画像生成API

コードはOpenAI画像API経由で、ClaudeはMCP経由でアクセスします。どちらの場合も、APIサーバーはすでにダウンロード済みのモデルを実行し、完成した画像を返します。

### OpenAI互換

OpenAI SDKの接続先をMacにして、`images.generate`を呼び出します。OpenAI向けに書かれたほとんどの画像コードで変わるのは、ベースURLとキーの2か所だけです。

### ClaudeはMCP経由で接続

Private DiffusionをClaude CodeまたはClaude Desktopに追加してから、Claudeに画像を頼みます。Claudeが`generate_image`ツールを呼び出すと、Macが画像を生成して返します。

### Mac上で生成

プロンプトと画像はクライアントとMacの間を移動し、クラウド中継はありません。Macにアクセスできるデバイスならリクエストを送信でき、Macはキーを持つリクエストにだけ応答します。

## 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コピー

```
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回リトライしてからエラーを送出します。

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は、Node.jsで動く小さなブリッジである`mcp-remote`を通じてサーバーにアクセスします。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フィールドを受け付け、PNGを指定しない限り圧縮率を85に設定した`jpeg`を返します。準備できていないモデルを明示的に指定すると、フォールバックではなくエラーになります。 |
| `list_models` | このMacで準備済みのモデルと、それぞれがここで受け付けるサイズ、ステップ、アップスケール倍率を一覧表示します。 |
| `get_image_chunk` | フルサイズ画像を表示する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に従いますが、独自のフィールドがいくつかあります。

リクエストパラメータ
| パラメータ | 値 | デフォルト | 注記 |
| --- | --- | --- | --- |
| `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`を使う場合のみ使用します。 |

#### レスポンス

画像はURLではなく`b64_json`内のbase64として返され、それぞれに`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`

シード付きの完成画像。複数枚を指定した場合、画像ごとに1つです。

 |
| `error` | `error`

ストリーム開始後に失敗が発生しました。それ以前のエラーは通常のJSONレスポンスとして届きます。

 |

最後の画像の後にストリームが閉じます。個別の完了イベントはありません。

### `GET /v1/models`

このMacでダウンロード済み、準備済み、かつ対応しているモデルを一覧表示します。そのIDのいずれかを`model`として送信します。

## APIで使えるモデル

Private Diffusionの各モデルは、ダウンロード済みで、お使いのMacが対応していれば、API経由で利用できます。2列目の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は、Studioがより高速な4ステップモードに設定されている場合でも、API経由では常に8ステップで実行されます。

サイズとアップスケール倍率は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ではありません。問題のあるフィールドが1つの場合は、`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枚。
-   一度に1枚、最大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では一度に1枚の画像を生成します。最大8件のリクエストが順番待ちになり、キューが進むまで次のリクエストには429エラーが返ります。OpenAI SDKは、デフォルトでそのエラーを2回リトライしてから諦めます。
    
-   ### iPhoneまたはiPadで使えますか？
    
    いいえ。APIサーバーはMac版Private Diffusionの機能です。iPhoneとiPadでは、アプリ内で画像を生成します。
    

このページの内容

1.  [概要](#overview)
2.  [セットアップ](#setup)
3.  [接続前に確認](#before-you-connect)
4.  [例](#examples)
5.  [ClaudeとMCP](#mcp)
6.  [認証](#authentication)
7.  [エンドポイント](#endpoints)
8.  [モデル](#models)
9.  [エラーと制限](#errors)
10.  [よくある質問](#faq)