Servidor de API · Mac
Agora, seu Mac é um servidor de geração de imagens
Inicie o Servidor de API no Private Diffusion e seu Mac responderá a solicitações de imagens do Claude, de scripts e de qualquer app que fale a API de imagens da OpenAI. Cada imagem é criada no seu Mac, sem retransmissão pela nuvem no meio.
- Somente Mac
- Beta
Configure com seu agente de IA
Cole este prompt no Claude Code ou em qualquer agente de programação. O agente verifica se o servidor de API no seu Mac está em execução e, em seguida, configura o MCP ou um script no seu próprio código.
Download https://privatediffusion.ai/agent-setup.md with curl, read it in full, and follow it to connect me to the Private Diffusion API server on my Mac.
API de geração de imagens compatível com OpenAI, servida pelo seu Mac
O código a acessa pela API de imagens da OpenAI, e o Claude a acessa pelo MCP. De qualquer forma, o Servidor de API executa os modelos que você já baixou e devolve imagens prontas.
Compatível com OpenAI
Aponte um SDK da OpenAI para o seu Mac e chame images.generate. A maior parte do código de imagem escrito para a OpenAI muda em dois pontos: a URL base e a chave.
Claude conecta pelo MCP
Adicione o Private Diffusion ao Claude Code ou Claude Desktop e peça uma imagem ao Claude. Ele chama a ferramenta generate_image, e seu Mac cria a imagem e a devolve.
Criado no seu Mac
Prompts e imagens trafegam entre seu cliente e seu Mac, sem retransmissão pela nuvem. Qualquer dispositivo que consiga acessar seu Mac pode enviar solicitações, e ele responde apenas às que incluem sua chave.
Configure em três etapas
- 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
Inicie o Servidor de API
Clique em Start API Server na aba API Server ou use o menu Server (⇧⌘A). Para servir sempre que o app abrir, ative "Start the API server at launch" em Settings › API Server.
- 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 "Start the API server at launch" 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.pngPython (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",
"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"
}
}
}
}Requer Node.js. A versão da ponte é fixada.
Ferramentas MCP
| Ferramenta | O que faz |
|---|---|
generate_image | Cria de uma a 4 imagens a partir de um prompt. Aceita os campos HTTP, exceto quality e streaming, e retorna jpeg com a compressão definida como 85, a menos que você peça PNG. Um modelo explícito que não está pronto é um erro, não uma alternativa. |
list_models | Lista os modelos prontos neste Mac com os tamanhos, etapas e fatores de ampliação que cada um aceita aqui. |
get_image_chunk | Usada por clientes MCP que exibem imagens em tamanho completo. Você nunca a chama diretamente. |
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.
| Parâmetro | Valores | Padrão | Observações |
|---|---|---|---|
prompt | string | Obrigatório | O que desenhar. Não pode ficar vazio. |
model | string | Modelo ativo | Um ID de modelo da tabela abaixo. Um ID desconhecido, não baixado ou não compatível com este Mac usa o modelo ativo como alternativa, e o model da resposta indica qual foi executado. |
n | 1–4 | 1 | Quantas imagens. Cada uma usa a próxima seed. |
size | "auto" | "WxH" | "auto" | Ajusta para o tamanho mais próximo aceito pelo modelo, primeiro pela forma e depois pela área. "auto" escolhe 1024×1024 quando o modelo permite. Tamanhos muito grandes exigem um Mac com mais memória. |
quality | "auto" | "low" | "medium" | "high" | "auto" | Apenas "high" muda o resultado, trocando velocidade por detalhe. Não tem efeito no Nanosaur 2 nem no MOSS-Image. |
output_format | "png" | "jpeg" | "png" | O formato do arquivo de imagem. |
output_compression | 0–100 | 100 | Compressão para saída JPEG. 100 é a menor compressão. |
seed | integer | Aleatório | Defina-o para repetir um resultado. |
negative_prompt | string | Nenhum | O que manter fora da imagem. Apenas alguns modelos; os demais retornam 400. MOSS-Image aceita, mas só lê em Quality. |
steps | integer | Padrão do modelo | Deve estar dentro do intervalo do modelo. Modelos de etapas fixas aceitam apenas seu próprio valor. MOSS-Image aceita apenas 50, que executa Quality; omita steps para o modo 4-step, que precisa do adaptador instalado. |
upscale | 1.5 | 2 | 4 | Nenhum | Amplia a imagem depois que ela é criada. O modelo precisa oferecer o fator e seu ampliador precisa estar baixado, ou a solicitação retorna 400. Nanosaur 2 não tem ampliador. Em Macs com menos memória, 4 passa a ser 2. |
stream | boolean | false | Envia o resultado como eventos enviados pelo servidor, com prévias opcionais em todos os modelos, exceto Nanosaur 2. |
partial_images | 0–3 | 0 | Quantas prévias transmitir antes da imagem final. Usado apenas com stream. Nanosaur 2 envia apenas a imagem final. |
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.
| Evento | Dados |
|---|---|
image_generation.partial_image | type, b64_json, partial_image_index, created_at, watermarkedUma prévia enquanto a imagem é criada. O índice recomeça em 0 para cada imagem. |
image_generation.completed | type, b64_json, seed, watermarked, sensitive, created_atA imagem final com sua seed. Uma por imagem quando você pede mais de uma. |
error | errorAlgo falhou depois que o stream foi aberto. Erros anteriores chegam como uma resposta JSON normal. |
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.
| Modelo | ID | Prompt negativo | Etapas | Ampliação |
|---|---|---|---|---|
| Anima | anima | Não | 8-12, padrão 8 | 2× |
| Flux.2 Klein 4B | klein | Sim | 4 | 1,5×, 2× |
| Nanosaur 2 | nanosaur2 | Não | 4 | Não |
| Mage Flow Turbo | mage-flow-turbo | Não | 4 | 1,5×, 2× |
| MOSS-Image | moss-image | Sim | 4 por padrão com o adaptador (6 em XL), ou 50 para Quality | 1,5×, 2× |
| Krea 2 Turbo | krea2-turbo | Não | 8 | 2× |
| Kroma Turbo | kroma | Sim | 8-12, padrão 10 | 2× |
| Z-Image-Turbo | zit | Sim | 9 | 2×, 4× |
| Juggernaut Z Fast | juggernaut-z | Sim | 8 | 2×, 4× |
| ERNIE Image Turbo | ernie-turbo | Não | 8 | 1,5×, 2× |
| Chroma1-Flash | chroma | Sim | 12 | 2×, 4× |
| Boogu Image Turbo | boogu | Não | 4 | 2×, 4× |
Krea 2 Turbo sempre executa 8 etapas pela API com o adaptador desativado, independentemente da configuração em Studio.
Quando você omite steps, MOSS-Image executa o modo 4-step (seis etapas em XL) se o adaptador estiver instalado, e Quality se não estiver. Envie steps: 50 para Quality, que leva bem mais tempo e é o único modo que lê negative_prompt; qualquer outro valor de steps retorna 400.
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
}
}| Status | Tipo e código | Quando |
|---|---|---|
| 400 | invalid_request_error | Um campo está ausente ou fora do intervalo, ou o corpo não é um JSON válido. Quando um campo é o causador, param o identifica. |
| 401 | invalid_request_error · invalid_api_key | A chave está ausente ou incorreta. |
| 404 | invalid_request_error · not_found | O caminho ou método não existe. |
| 405 | — | Uma solicitação diferente de POST foi enviada para /mcp. |
| 413 | invalid_request_error · request_too_large | O corpo é maior que 2 MiB. |
| 429 | rate_limit_error · queue_full | A fila já contém 8 solicitações. Tente novamente em instantes. |
| 500 | server_error · generation_failed · internal_error | A geração falhou no Mac. |
| 503 | server_error · server_stopping · runtime_unavailable · model_unavailable | O servidor está parando, o mecanismo precisa de um momento ou não há modelo ativo. Tente novamente após os segundos indicados em Retry-After. |
- 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-Afterde 10 segundos.
Perguntas frequentes
Conecte o Claude Code ou Claude Desktop ao Private Diffusion pelo MCP com o endereço e a chave de Details na aba API Server do app. Depois, peça uma imagem ao Claude. O Claude chama o Private Diffusion, que cria a imagem no seu Mac e a devolve.
Sim, para gerar imagens. Aponte um SDK da OpenAI para o endereço do seu Mac com sua chave, e a chamada de geração de imagens funciona como na OpenAI. As diferenças: as imagens retornam como base64, não há edição nem entrada de imagem, e você recebe campos extras como seed e prompt negativo.
Sim. Qualquer dispositivo que consiga acessar seu Mac pode usá-lo com sua chave. Use o endereço de Details na aba API Server do app.
Não. O servidor usa HTTP simples, então use-o em redes confiáveis, mantenha a chave privada e gere outra se ela vazar.
Todos os modelos que você baixou no seu Mac. Cada um mantém suas próprias regras de etapas, prompts negativos e ampliação, listadas na tabela desta página.
Seu Mac cria uma imagem por vez. Até 8 solicitações aguardam na fila, e a próxima recebe um erro 429 até que a fila avance. Por padrão, os SDKs da OpenAI tentam novamente esse erro duas vezes antes de desistir.
Não. O Servidor de API faz parte do Private Diffusion para Mac. No iPhone e iPad, você gera imagens no próprio app.