AIProxyServer - Handleiding

Aan de slag

1. Start de app

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

• Proxyserver — huidige status, basis-URL en een knop om de listener te starten of te stoppen
• Bearer Token — optionele authenticatieschakelaar en tokenweergave
• Providers — elke ondersteunde cloud-AI-provider, met een API-sleutel instellen knop op elke rij

2. Voeg je eerste API-sleutel toe

1. Kies een provider uit de lijst Providers (bijvoorbeeld OpenAI (ChatGPT))
2. Klik op API-sleutel ophalen om de console van de provider in je browser te openen en daar een sleutel aan te maken of te kopiëren
3. Klik op API-sleutel instellen op dezelfde rij en plak de waarde in het dialoogvenster
4. Klik op Opslaan. Het statuslabel verandert in Geconfigureerd in het groen

3. Verbind een client-app

Richt elke OpenAI-compatibele client op de proxy. De basis-URL is http://localhost:8421/<provider>/v1. Het providersegment bepaalt welke cloud het verzoek ontvangt.

# Example: OpenAI Python SDK pointed at the 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 de echte sleutel nooit. AIProxyServer voegt de upstream-inloggegevens toe op het moment dat het verzoek wordt doorgestuurd.

Overzicht van de interface

Paneel Proxyserver

Paneel Bearer Token

• Bearer Token-authenticatie vereisen — selectievakje dat authenticatie in- of uitschakelt. Standaard uit voor moeiteloos lokaal gebruik.
• Tokenveld — alleen-lezen weergave van het huidige token. Wordt als puntjes getoond; gebruik Kopiëren om het op te halen.
• Opnieuw genereren — geeft een nieuw willekeurig token uit. Bestaande clients moeten de nieuwe waarde krijgen.

Paneel Providers

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

• De weergavenaam (bijvoorbeeld Claude (Anthropic))
• Configuratiestatus — groen Geconfigureerd wanneer een API-sleutel is opgeslagen, grijs Niet geconfigureerd in andere gevallen
• Het URL-pad dat je clients gebruiken, bijv. /anthropic/v1/chat/completions
• API-sleutel instellen — opent een dialoogvenster om inloggegevens in te voeren
• API-sleutel ophalen — opent de console van de provider in je browser

Ondersteunde providers

Er zijn elf cloud-AI-diensten meegeleverd. De meeste gebruiken standaard het OpenAI Chat Completions-formaat en worden ongewijzigd doorgestuurd. Drie ervan (Anthropic, Gemini, ERNIE) spreken hun eigen protocol; AIProxyServer vertaalt verzoeken en antwoorden direct, zodat je client altijd alleen OpenAI-vormen te zien krijgt.

Providerspecifieke opmerkingen

• Azure OpenAI — plak het volledige deployment-endpoint in het veld Endpoint-basis-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 op de achtergrond toegangstokens aan en bewaart die tijdelijk.
• Gemini — authenticatie verloopt via een URL-queryparameter; de proxy voegt die voor je toe. De limieten per minuut van het gratis niveau blijven gelden.

API-referentie

Eindpunten

Streaming

Wanneer de client "stream": trueverstuurt, antwoordt de proxy met Server-Sent Events in het formaat van 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]

Native streams van Anthropic en Gemini worden naar deze vorm vertaald, zodat alle clients met één parser toekunnen.

Authenticatieheader

Wanneer Bearer Token-authenticatie vereisen aanstaat, stuur je bij elk verzoek het token uit het hoofdvenster mee:

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

Instellingen

Open het venster Instellingen via het tandwielpictogram in de onderste werkbalk.

Voorbeelden voor clients

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 the same OpenAI shape
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",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

Tips

• Laat Bearer Token uit terwijl je lokaal ontwikkelt; zet het aan zodra je LAN-toegang inschakelt.
• Gebruik in je clientcode aparte basis-URL's per provider, zodat je van provider kunt wisselen door één constante aan te passen.
• De proxy start automatisch, maar je kunt hem tijdelijk stoppen vanuit het hoofdvenster als er een poortconflict optreedt.
• Als het gratis niveau van een provider je snelheid beperkt, wordt de upstream-foutmelding letterlijk doorgegeven. Er wordt geen herhaallogica voor de client verborgen.
• Het /v1/providers -endpoint is handig om tijdens runtime te zien welke providers zijn geconfigureerd.

Problemen oplossen

De proxy start niet

• Mogelijk gebruikt een ander proces poort 8421 al. Wijzig de poort in Instellingen en start de proxy opnieuw.
• Bekijk het systeemlogboek voor de foutmelding die bij het starten werd getoond.

Een verzoek geeft 401 Unauthorized terug

• De Bearer Token-vereiste staat aan, maar de client stuurde geen bijpassende Authorization: Bearer ... -header mee.
• De eigen API-sleutel van de provider kan ongeldig zijn — de upstream-fout wordt doorgegeven, dus controleer de berichttekst.

Een verzoek geeft "API key is not configured" terug

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

Mobiel apparaat kan de proxy niet bereiken

• Schakel LAN-toegang toestaan in Instellingen in.
• Gebruik het LAN-IP dat in het veld Basis-URL staat, niet localhost.
• Zorg dat beide apparaten op hetzelfde Wi-Fi-netwerk zitten en dat je firewall inkomende verbindingen op de proxypoort toestaat.

Streamingantwoorden komen in één keer binnen

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

Privacy

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