Servidor de API · Mac

# Seu Mac agora é uma API 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

[![Pré-encomendar na App Store](/app-store/pre-order-badge/pt-BR/pre-order.svg)![Pré-encomendar na App Store](/app-store/pre-order-badge/pt-BR/pre-order-dark.svg)](https://testflight.apple.com/join/DQwfQsEg)[Discord](https://discord.com/invite/g2vMMbtHRt)

Nesta página

1.  [Visão geral](#overview)
2.  [Configuração](#setup)
3.  [Antes de conectar](#before-you-connect)
4.  [Exemplos](#examples)
5.  [Claude e MCP](#mcp)
6.  [Autenticação](#authentication)
7.  [Endpoints](#endpoints)
8.  [Modelos](#models)
9.  [Erros e limites](#errors)
10.  [Perguntas frequentes](#faq)

## 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.  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`.

curlCopiar

```
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.

PythonCopiar

```
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.

JavaScriptCopiar

```
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.

TerminalCopiar

```
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.

claude\_desktop\_config.jsonCopiar

```
{
  "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

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âmetros da solicitação
| 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"` | Somente `"high"` muda o resultado, trocando velocidade por detalhes. |
| `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 aceitam; os demais retornam 400. |
| `steps` | integer | Padrão do modelo | Deve ficar dentro do intervalo do modelo. Modelos de etapas fixas aceitam apenas seu próprio valor. |
| `upscale` | 1.5 | 2 | 4 | Nenhum | Amplia a imagem depois de criada. O modelo deve oferecer o fator e seu ampliador deve estar baixado, ou a solicitação retorna 400. Em Macs com menos memória, 4 vira 2. |
| `stream` | boolean | `false` | Envia o resultado como eventos enviados pelo servidor, com prévias opcionais. |
| `partial_images` | 0–3 | `0` | Quantas prévias transmitir antes da imagem final. Usado apenas com `stream`. |

#### 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.

JSONCopiar

```
{
  "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.

Imagens parciais por streaming
| Evento | Dados |
| --- | --- |
| `image_generation.partial_image` | `type, b64_json, partial_image_index, created_at, watermarked`
Uma 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_at`

A imagem final com sua seed. Uma por imagem quando você pede mais de uma.

 |
| `error` | `error`

Algo 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`.

Quais modelos funcionam pela API
| 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× |
| Mage Flow Turbo | `mage-flow-turbo` | Não | 4 | 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, 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.

JSONCopiar

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

Erros e limites
| 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-After` de 10 segundos.

## Perguntas frequentes

-   ### Como gerar imagens com o Claude?
    
    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.
    
-   ### É compatível com a API de imagens da OpenAI?
    
    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.
    
-   ### Outros dispositivos na minha rede podem usá-lo?
    
    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.
    
-   ### A conexão é criptografada?
    
    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.
    
-   ### Quais modelos funcionam pela API?
    
    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.
    
-   ### O que acontece quando várias solicitações chegam ao mesmo tempo?
    
    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.
    
-   ### Funciona no iPhone ou iPad?
    
    Não. O Servidor de API faz parte do Private Diffusion para Mac. No iPhone e iPad, você gera imagens no próprio app.
    

Nesta página

1.  [Visão geral](#overview)
2.  [Configuração](#setup)
3.  [Antes de conectar](#before-you-connect)
4.  [Exemplos](#examples)
5.  [Claude e MCP](#mcp)
6.  [Autenticação](#authentication)
7.  [Endpoints](#endpoints)
8.  [Modelos](#models)
9.  [Erros e limites](#errors)
10.  [Perguntas frequentes](#faq)