Seu Mac agora é uma API de geração de imagens

Configure em três etapas

1. 1

   Baixe um modelo

   Abra o Private Diffusion no seu Mac e baixe pelo menos um modelo. O servidor gera com os modelos que você tem, e o modelo ativo no Studio é o padrão.

2. 2

   Inicie o Servidor de API

   Clique em Iniciar servidor de API na aba Servidor de API ou use o menu Servidor (⇧⌘A). Para servir sempre que o app abrir, ative "Iniciar o servidor de API ao abrir" em Ajustes › Servidor de API.

3. 3

   Copie seu endereço e sua chave

   Clique em Details na aba API Server. Lá estão os endereços do seu Mac, sua chave e comandos prontos para curl, Claude Code e Claude Desktop, com ambos já preenchidos.

Saiba antes de conectar

• O servidor usa HTTP simples. Sua chave, seus prompts e suas imagens atravessam a rede sem criptografia, então use-o em redes confiáveis e pare-o em redes Wi-Fi públicas.
• Qualquer dispositivo que consiga acessar seu Mac e tenha a chave pode gerar imagens.
• Trate a chave como uma senha. Se ela vazar, gere outra em Settings › API Server. Os clientes que usam a chave antiga param de funcionar até você fornecer a nova.
• Qualquer página da web à qual você fornecer a chave pode chamar o servidor pelo navegador. Cole-a apenas em ferramentas confiáveis.
• Com "Iniciar o servidor de API ao abrir" ativado, seu Mac atende em todas as redes às quais se conecta. Desative essa opção em um laptop que você leva consigo.
• Enquanto o servidor estiver em execução, o Studio pausa, seu Mac permanece ativo, e a troca ou exclusão de modelos espera até que você o pare.
• As imagens criadas pela API vão para sua galeria. Ative o Incognito Mode ou desative Save API images to gallery para mantê-las fora dela.
• Seu Mac cria uma imagem por vez. Até 8 solicitações aguardam a vez, e a próxima recebe um erro queue_full.

Gere imagens com curl, Python e JavaScript

Cada exemplo cria uma imagem e a salva como arquivo. Coloque sua chave em uma variável de ambiente chamada PD_API_KEY e substitua your-mac.local pelo endereço do seu Mac em Details, na aba API Server.

8963 é a porta padrão. Se você a alterou em Settings › API Server, use a sua.

curl

Envia o prompt e decodifica a imagem retornada com 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)

Usa o pacote oficial openai. Campos que a API da OpenAI não define, como seed, ficam em extra_body. Por padrão, o SDK tenta novamente uma fila cheia duas vezes e depois gera o erro.

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)

Executa no Node.js com o pacote openai, que envia campos extras como seed sem alterações. Nunca o execute em uma página da web, onde qualquer pessoa poderia ler a chave.

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"));

Geração de imagens do Claude pelo MCP: Claude Code e Claude Desktop

O Private Diffusion fala o Model Context Protocol em /mcp. Conecte o Claude uma vez e depois peça imagens em linguagem natural.

Claude Code

Com PD_API_KEY definido como acima, execute isto uma vez no Terminal para adicionar o servidor ao Claude Code.

claude mcp add --transport http private-diffusion http://your-mac.local:8963/mcp \
  --header "Authorization: Bearer $PD_API_KEY"

Não adicione --scope project. Isso grava sua chave em um arquivo .mcp.json destinado ao compartilhamento.

Claude Desktop

O Claude Desktop acessa o servidor por mcp-remote, uma pequena ponte executada no Node.js. No Claude Desktop, abra Settings › Developer › Edit Config, adicione esta entrada, substitua pd-your-key pela sua chave e reinicie o 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"
      }
    }
  }
}

Requer Node.js. A versão da ponte é fixada.

Ferramentas MCP

Autenticação

Cada solicitação para /v1/* e /mcp leva sua chave no cabeçalho Authorization: Bearer pd-…. O app cria a chave na primeira vez que o servidor é iniciado. Revele-a ou gere outra em Settings › API Server.

Uma chave ausente ou incorreta retorna 401 com o código invalid_api_key.

Endpoints: /v1/images/generations, /v1/models e /mcp

POST /v1/images/generations

Gera imagens a partir de um prompt de texto. As solicitações e respostas seguem a API de imagens da OpenAI, com alguns campos próprios.

Resposta

As imagens retornam como base64 em b64_json, nunca como URL, cada uma com sua seed e a indicação de marca d'água. model informa o modelo executado.

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

Imagens parciais por streaming

Defina stream como true e o servidor responderá com eventos enviados pelo servidor. Cada quadro informa seu evento e contém um objeto JSON.

O stream é fechado após a última imagem. Não há evento done separado.

GET /v1/models

Lista os modelos baixados, prontos e aceitos neste Mac. Envie um dos IDs deles como model.

Quais modelos funcionam pela API

Todos os modelos do Private Diffusion funcionam pela API depois de baixados, desde que o Mac seja compatível. Envie o ID da segunda coluna como model.

Krea 2 Turbo sempre executa 8 etapas pela API, mesmo quando o Studio está configurado para o modo mais rápido de 4 etapas.

Os tamanhos e fatores de ampliação dependem da memória do seu Mac. A ferramenta MCP list_models informa o que seu Mac aceita.

Erros e limites

Os erros seguem o formato da OpenAI: um objeto JSON com uma mensagem, um tipo, o parâmetro com problema e um código.

{
  "error": {
    "message": "steps must be between 8 and 12 for Kroma Turbo.",
    "type": "invalid_request_error",
    "param": "steps",
    "code": null
  }
}

• Corpos de solicitação de até 2 MiB.
• De uma a 4 imagens por solicitação.
• Uma imagem por vez, com até 8 aguardando.
• Todo 503 inclui Retry-After de 10 segundos.

Perguntas frequentes