API 서버 · Mac

# 이제 Mac이 이미지 생성 API가 됩니다

Private Diffusion에서 API 서버를 시작하면 Mac이 Claude, 스크립트 및 OpenAI 이미지 API를 지원하는 모든 앱의 이미지 요청에 응답합니다. 모든 이미지는 중간 클라우드 중계 없이 Mac에서 만들어집니다.

-   Mac 전용
-   베타

[![App Store에서 사전 주문](/app-store/pre-order-badge/ko/pre-order.svg)![App Store에서 사전 주문](/app-store/pre-order-badge/ko/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](#faq)

## Mac에서 제공하는 OpenAI 호환 이미지 생성 API

코드는 OpenAI 이미지 API를 통해 연결하고, Claude는 MCP를 통해 연결합니다. 어느 쪽이든 API 서버는 이미 다운로드한 모델을 실행하고 완성된 이미지를 반환합니다.

### OpenAI 호환

OpenAI SDK가 Mac을 가리키도록 설정하고 `images.generate`를 호출하세요. OpenAI용으로 작성한 대부분의 이미지 코드는 기본 URL과 키, 두 곳만 바꾸면 됩니다.

### Claude는 MCP로 연결

Private Diffusion을 Claude Code 또는 Claude Desktop에 추가한 다음 Claude에게 그림을 요청하세요. Claude가 `generate_image` 도구를 호출하면 Mac이 이미지를 만들어 반환합니다.

### Mac에서 생성

프롬프트와 이미지는 클라우드 중계 없이 클라이언트와 Mac 사이를 오갑니다. Mac에 연결할 수 있는 모든 기기는 요청을 보낼 수 있고, Mac은 키가 포함된 요청에만 응답합니다.

## 3단계로 설정하기

1.  1
    
    ### 모델 다운로드
    
    Mac에서 Private Diffusion을 열고 모델을 하나 이상 다운로드하세요. 서버는 보유한 모델로 이미지를 생성하며, Studio에서 활성화된 모델이 기본값입니다.
    
2.  2
    
    ### API 서버 시작
    
    API Server 탭에서 Start API Server를 클릭하거나 Server 메뉴(⇧⌘A)를 사용하세요. 앱을 열 때마다 서버를 실행하려면 Settings › API Server에서 "Start the API server at launch"를 켜세요.
    
3.  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복사

```
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는 기본적으로 꽉 찬 대기열을 두 번 재시도한 뒤 오류를 발생시킵니다.

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`

시드가 포함된 완성 이미지입니다. 여러 장을 요청하면 이미지마다 하나씩 제공됩니다.

 |
| `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는 Studio가 더 빠른 4-step 모드로 설정되어 있어도 API에서는 항상 8 step으로 실행됩니다.

크기와 업스케일 배율은 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까지 가능합니다.
-   요청당 이미지 한 장에서 4장까지 가능합니다.
-   한 번에 이미지 하나, 최대 8개가 대기합니다.
-   모든 503에는 10초의 `Retry-After`가 포함됩니다.

## FAQ

-   ### Claude로 이미지를 어떻게 생성하나요?
    
    앱의 API Server 탭에 있는 Details의 주소와 키를 사용해 Claude Code 또는 Claude Desktop을 MCP로 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에서는 앱에서 직접 이미지를 생성합니다.
    

이 페이지에서

1.  [개요](#overview)
2.  [설정](#setup)
3.  [연결하기 전에](#before-you-connect)
4.  [예시](#examples)
5.  [Claude 및 MCP](#mcp)
6.  [인증](#authentication)
7.  [엔드포인트](#endpoints)
8.  [모델](#models)
9.  [오류 및 제한](#errors)
10.  [FAQ](#faq)