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

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

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로 사용할 수 있습니다. 두 번째 열의 id를 model으로 보내세요.

Krea 2 Turbo는 Studio가 더 빠른 4-step 모드로 설정되어 있어도 API에서는 항상 8 step으로 실행됩니다.

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

FAQ