AIProxyServer - Handleiding

Aan de slag

1. Start de app

Open AIProxyServer. Bij de eerste start start de proxy automatisch en luistert op poort 8421 van je lokale machine. Het hoofdvenster toont drie secties:

• Proxy Server — huidige status, base URL en een knop om de listener te starten of stoppen
• Bearer Token — optionele authenticatieschakelaar en tokenweergave
• Providers — elke ondersteunde cloud-AI-provider, met een Set API Key-knop per rij

2. Voeg je eerste API-sleutel toe

1. Kies een willekeurige provider uit de lijst Providers (bijvoorbeeld OpenAI (ChatGPT))
2. Klik op Get API key om de console van de provider in je browser te openen, maak vervolgens een sleutel aan of kopieer er een
3. Klik op Set API Key op dezelfde rij en plak de waarde in het dialoogvenster
4. Klik op Save. Het statuslabel verandert naar Configured in groen

3. Verbind een client-app

Richt elke OpenAI-compatibele client op de proxy. De Base URL is http://localhost:8421/<provider>/v1. Het provider-segment bepaalt welke cloud de aanvraag ontvangt.

# Voorbeeld: OpenAI Python SDK gericht op de 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)

De client ziet nooit de echte sleutel. AIProxyServer voegt de upstream-inloggegevens toe wanneer het de aanvraag doorstuurt.

Interface-overzicht

Proxy Server-paneel

Bearer Token-paneel

• Require Bearer Token authentication — selectievakje dat authenticatie aan- of uitzet. Standaard uit voor onbezorgd lokaal gebruik.
• Token field — alleen-lezen weergave van het huidige token. Wordt als stippen getoond; gebruik Copy om het te pakken.
• Regenerate — geef een nieuw willekeurig token uit. Bestaande clients moeten worden bijgewerkt met de nieuwe waarde.

Providers-paneel

Eén rij per ondersteunde cloudprovider. Elke rij toont:

• De weergavenaam (bijvoorbeeld Claude (Anthropic))
• Configuratiestatus — groen Configured wanneer een API-sleutel is opgeslagen, anders grijs Not configured
• Het URL-pad dat je clients gebruiken, bijv. /anthropic/v1/chat/completions
• Set API Key — opent een dialoogvenster om inloggegevens in te voeren
• Get API key — opent de console van de provider in je browser

Ondersteunde providers

Elf cloud-AI-services zijn meegeleverd. De meeste gebruiken het OpenAI Chat Completions-formaat natief en worden zonder wijzigingen doorgestuurd. Drie (Anthropic, Gemini, ERNIE) spreken hun eigen protocollen; AIProxyServer vertaalt aanvragen en antwoorden direct, zodat je client altijd alleen OpenAI-vormen ziet.

Provider-specifieke opmerkingen

• Azure OpenAI — plak de volledige deployment-endpoint in het veld Endpoint Base URL, bijvoorbeeld https://my-resource.openai.azure.com/openai/deployments/gpt-4o. De proxy voegt automatisch /chat/completions?api-version=2024-02-01 toe.
• ERNIE — Baidu Qianfan gebruikt OAuth, dus zowel API Key als Secret Key zijn vereist. AIProxyServer vraagt access-tokens aan en cachet ze op de achtergrond.
• Gemini — authenticatie verloopt via een URL-queryparameter; de proxy voegt deze voor je toe. Gratis-tier-quota per minuut blijven van toepassing.

API-referentie

Endpoints

Streaming

Wanneer de client "stream": true verstuurt, antwoordt de proxy met Server-Sent Events in OpenAI's formaat:

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

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

data: [DONE]

Native streams van Anthropic en Gemini worden naar deze vorm vertaald zodat alle clients één enkele parser kunnen gebruiken.

Authenticatiekop

Wanneer Require Bearer Token authentication aanstaat, stuur het token uit het hoofdvenster mee met elke aanvraag:

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

Instellingen

Open het instellingenvenster via het tandwielpictogram in de onderste werkbalk.

Clientvoorbeelden

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 via dezelfde OpenAI-vorm
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",  # genegeerd wanneer Bearer Token uit staat
)
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

// Met een willekeurige OpenAI-compatibele Dart-client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // ongebruikt wanneer Bearer Token uit staat
);

Tips

• Laat Bearer Token uit terwijl je lokaal aan het ontwikkelen bent; zet hem aan op het moment dat je LAN-toegang inschakelt.
• Gebruik per provider verschillende Base URLs in je clientcode, zodat je providers kunt wisselen door één constante te wijzigen.
• De proxy start automatisch maar je kunt hem tijdelijk stoppen vanuit het hoofdvenster als er een poortconflict optreedt.
• Als de gratis tier van een provider je beperkt qua snelheid, wordt de upstream-foutmelding letterlijk doorgestuurd. Er is geen retry-logica voor de client verborgen.
• Het /v1/providers-endpoint is handig om tijdens runtime te ontdekken welke providers zijn geconfigureerd.

Probleemoplossing

De proxy start niet

• Een ander proces gebruikt mogelijk al poort 8421. Wijzig de poort in de instellingen en herstart de proxy.
• Controleer het systeemlogboek voor de foutmelding die bij het starten wordt weergegeven.

Een aanvraag geeft 401 Unauthorized terug

• De Bearer Token-vereiste staat aan maar de client heeft geen overeenkomende Authorization: Bearer ...-header verzonden.
• De eigen API-sleutel van de provider kan ongeldig zijn — de upstream-fout wordt doorgestuurd, dus controleer de berichtinhoud.

Een aanvraag geeft "API key is not configured" terug

• Open de Providers-lijst en klik op Set API Key voor de betreffende provider.
• Voor ERNIE moeten zowel API Key als Secret Key worden ingevuld. Voor Azure OpenAI is ook de Endpoint Base URL vereist.

Mobiel apparaat kan de proxy niet bereiken

• Schakel Allow LAN Access in de instellingen in.
• Gebruik het LAN-IP dat in het Base URL-veld wordt weergegeven, niet localhost.
• Zorg dat beide apparaten zich op hetzelfde Wi-Fi-netwerk bevinden en dat je firewall inkomende verbindingen op de proxypoort toestaat.

Streaming-antwoorden komen in één keer aan

• Zorg dat je client "stream": true in de JSON-body verstuurt.
• Sommige HTTP-bibliotheken bufferen SSE standaard — schakel responsbuffering uit aan de clientzijde.

Privacy

• API-sleutels worden versleuteld met Fernet opgeslagen in ~/Library/Application Support/AIProxyServer/credentials.enc. De versleutelingssleutel in master.key heeft permissies 0600.
• Het Bearer Token wordt, indien ingeschakeld, ook alleen in de versleutelde kluis opgeslagen en nooit naar het reguliere instellingenbestand geschreven.
• De proxy stuurt aanvragen alleen door naar providers die je expliciet hebt geconfigureerd. Er worden geen andere uitgaande oproepen gedaan.
• Geen telemetrie, geen analytics, geen crashrapportage.
• Standaard netwerkbinding is alleen 127.0.0.1. Blootstelling aan de LAN is opt-in.
• Gespreksinhoud wordt niet opgeslagen. AIProxyServer stuurt bytes door en vergeet ze meteen.