AIProxyServer - Guia

Primeiros passos

1. Abra o aplicativo

Abra o AIProxyServer. Na primeira execução, o proxy inicia automaticamente e escuta na porta 8421 da sua máquina local. A janela principal mostra três seções:

• Proxy Server — status atual, URL base e um botão para iniciar ou parar o listener
• Bearer Token — chave de autenticação opcional e exibição do token
• Providers — todos os provedores de IA na nuvem suportados, com um botão Set API Key por linha

2. Adicione sua primeira chave de API

1. Escolha qualquer provedor da lista de Providers (por exemplo, OpenAI (ChatGPT))
2. Clique em Get API key para abrir o console do provedor no navegador, depois crie ou copie uma chave
3. Clique em Set API Key na mesma linha e cole o valor na caixa de diálogo
4. Clique em Save. O rótulo de status muda para Configured em verde

3. Conecte um app cliente

Aponte qualquer cliente compatível com OpenAI para o proxy. A Base URL é http://localhost:8421/<provider>/v1. O segmento provider escolhe qual nuvem receberá a requisição.

# Exemplo: OpenAI Python SDK apontado para o proxy
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

O cliente nunca vê a chave real. O AIProxyServer anexa as credenciais upstream ao encaminhar a requisição.

Visão geral da interface

Painel Proxy Server

Painel Bearer Token

• Require Bearer Token authentication — caixa de seleção que ativa ou desativa a autenticação. Desativada por padrão para uso local sem complicações.
• Token field — exibição somente leitura do token atual. Mostrado como pontos; use Copy para obtê-lo.
• Regenerate — emite um novo token aleatório. Os clientes existentes devem ser atualizados com o novo valor.

Painel Providers

Uma linha por provedor de nuvem suportado. Cada linha mostra:

• O nome de exibição (por exemplo, Claude (Anthropic))
• Status de configuração — verde Configured quando uma chave de API está salva, cinza Not configured caso contrário
• O caminho de URL que seus clientes usam, ex.: /anthropic/v1/chat/completions
• Set API Key — abre uma caixa de diálogo para inserir as credenciais
• Get API key — abre o console do provedor no navegador

Provedores suportados

Onze serviços de IA na nuvem vêm incluídos. A maioria usa nativamente o formato OpenAI Chat Completions e é proxiada sem alterações. Três (Anthropic, Gemini, ERNIE) falam seus próprios protocolos; o AIProxyServer traduz requisições e respostas em tempo real para que seu cliente sempre veja apenas formatos OpenAI.

Notas específicas por provedor

• Azure OpenAI — cole o endpoint completo da implantação no campo Endpoint Base URL, por exemplo https://my-resource.openai.azure.com/openai/deployments/gpt-4o. O proxy acrescenta /chat/completions?api-version=2024-02-01 automaticamente.
• ERNIE — o Baidu Qianfan usa OAuth, então tanto API Key quanto Secret Key são necessárias. O AIProxyServer solicita e armazena em cache os tokens de acesso nos bastidores.
• Gemini — a autenticação é feita por parâmetro de consulta de URL; o proxy o adiciona para você. As cotas por minuto da camada gratuita ainda se aplicam.

Referência da API

Endpoints

Streaming

Quando o cliente envia "stream": true, o proxy responde com Server-Sent Events no formato OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Os streams nativos da Anthropic e do Gemini são traduzidos para esse formato, de modo que todos os clientes possam usar um único parser.

Cabeçalho de autenticação

Quando Require Bearer Token authentication está ativado, envie o token mostrado na janela principal em cada requisição:

Authorization: Bearer <token-shown-in-app>

Configurações

Abra a janela de Configurações pelo ícone de engrenagem na barra de ferramentas inferior.

Exemplos de cliente

cURL

# OpenAI (passthrough)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude no mesmo formato OpenAI
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # ignorado quando o Bearer Token está desativado
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Usando qualquer cliente Dart compatível com OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // não utilizado quando o Bearer Token está desativado
);

Dicas

• Deixe o Bearer Token desativado enquanto estiver desenvolvendo localmente; ative-o no momento em que habilitar o acesso LAN.
• Use Base URLs distintas por provedor no código do cliente para poder trocar de provedor alterando apenas uma constante.
• O proxy inicia automaticamente, mas você pode pará-lo temporariamente pela janela principal se ocorrer um conflito de porta.
• Se a camada gratuita de um provedor limitar sua taxa, a mensagem de erro upstream é encaminhada literalmente. Nenhuma lógica de retry é ocultada do cliente.
• O endpoint /v1/providers é útil para descobrir quais provedores estão configurados em tempo de execução.

Solução de problemas

O proxy não inicia

• Outro processo pode já estar usando a porta 8421. Mude a porta nas configurações e reinicie o proxy.
• Verifique o log do sistema para a mensagem de erro exibida no momento da inicialização.

Uma requisição retorna 401 Unauthorized

• A exigência de Bearer Token está ativada, mas o cliente não enviou um cabeçalho Authorization: Bearer ... correspondente.
• A chave de API do próprio provedor pode estar inválida — o erro upstream é encaminhado, então verifique o corpo da mensagem.

Uma requisição retorna "API key is not configured"

• Abra a lista de Providers e clique em Set API Key para o provedor em questão.
• Para ERNIE, tanto API Key quanto Secret Key devem ser preenchidos. Para Azure OpenAI, o Endpoint Base URL também é obrigatório.

O dispositivo móvel não consegue alcançar o proxy

• Ative Allow LAN Access nas configurações.
• Use o IP de LAN exibido no campo Base URL, e não localhost.
• Certifique-se de que ambos os dispositivos estejam na mesma rede Wi-Fi e de que seu firewall permita conexões de entrada na porta do proxy.

As respostas em streaming chegam todas de uma vez

• Garanta que seu cliente envia "stream": true no corpo JSON.
• Algumas bibliotecas HTTP fazem buffer de SSE por padrão — desative o buffering de resposta no lado do cliente.

Privacidade

• As chaves de API são armazenadas criptografadas com Fernet em ~/Library/Application Support/AIProxyServer/credentials.enc. A chave de criptografia em master.key tem permissões 0600.
• O Bearer Token, quando ativado, também é armazenado apenas no cofre criptografado e nunca gravado no arquivo de configurações regular.
• O proxy só encaminha requisições para provedores que você configurou explicitamente. Não faz nenhuma outra chamada de saída.
• Sem telemetria, sem analytics, sem relatórios de falha.
• A vinculação de rede padrão é apenas 127.0.0.1. A exposição LAN é opt-in.
• O conteúdo das conversas não é armazenado. O AIProxyServer encaminha os bytes e os esquece imediatamente.