OpenAI-kompatible API: Base URL ändern

Mit einer OpenAI-kompatiblen API kann ein bestehender Client seine vertrauten Authentifizierungs-Header, JSON-Strukturen und Streaming-Abläufe beibehalten, obwohl die Anfragen an ein anderes Gateway gehen. Oft reichen eine neue Base URL und ein neuer API-Schlüssel. Kompatibilität bleibt jedoch ein Protokollvertrag und ist keine Zusage, dass jedes Modell jeden Endpunkt oder jedes anbieterspezifische Feld unterstützt.

Dieser Leitfaden beschreibt einen sicheren Wechsel für Anwendungen, Skripte und KI-Werkzeuge, die bereits eine API im OpenAI-Stil verwenden.

Was OpenAI-Kompatibilität tatsächlich umfasst

Besonders gut wiederverwendbar sind:

• Bearer-Authentifizierung über den Authorization-Header;
• JSON-Anfragen und -Antworten an versionierten /v1-Endpunkten;
• gängige Endpunkte wie /v1/models, /v1/chat/completions und /v1/responses;
• Server-Sent Events für unterstützte Streaming-Anfragen;
• bekannte Felder wie model, messages, input, stream und Tool-Definitionen, sofern das gewählte Protokoll sie vorsieht.

Kompatibilität bedeutet nicht, dass sich ein Modell beliebig zwischen Chat Completions und Responses verschieben lässt. Ein Modell kann nur für eines der beiden geprüften Protokolle freigeschaltet sein. Anbieterspezifische Felder für Reasoning, Suche oder multimodale Eingaben müssen unter Umständen unverändert durchgereicht werden, statt sie im Gateway zu übersetzen.

Der aktuelle Katalog Modelle & Preise ist die maßgebliche Quelle für Modell, Gruppe und unterstütztes API-Format.

Migration vorbereiten

Bevor Sie Anwendungscode ändern:

1. Legen Sie unter API-Schlüssel einen eigenen Schlüssel für die Integration an, statt einen persönlichen oder fachfremden Schlüssel wiederzuverwenden.
2. Wählen Sie eine primäre Modellgruppe, die Zugriff auf das gewünschte Modell hat.
3. Ergänzen Sie Fallback-Gruppen in klarer Reihenfolge und nur dann, wenn sie dasselbe Modell unterstützen und zur Kosten- und Verfügbarkeitsstrategie passen.
4. Halten Sie aktuellen Endpunkt, exakte Modell-ID, Streaming-Einstellung und Tool-Nutzung fest, damit sich das Verhalten vor und nach der Umstellung vergleichen lässt.

Die kanonische OpenAI-kompatible Base URL von Modelflare lautet:

https://modelflare.dev/v1

Die meisten SDKs erwarten eine Base URL bis einschließlich /v1 und hängen /chat/completions oder /responses selbst an. Prüfen Sie die Client-Dokumentation, bevor Sie einen Endpunkt doppelt angeben.

Zuerst Authentifizierung und Modellzugriff prüfen

Speichern Sie den Schlüssel in einer Umgebungsvariable und nicht im Quellcode:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Prüfen Sie anschließend, ob der Schlüssel seine verfügbaren Modelle auflisten kann:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Eine erfolgreiche Antwort bestätigt Hostname, TLS-Verbindung und Schlüssel. Sie beweist noch nicht, dass jedes zurückgegebene Modell jedes Anfrageformat akzeptiert. Der nächste Test muss deshalb den tatsächlich vorgesehenen Endpunkt verwenden.

Eine Anfrage mit dem vorgesehenen Protokoll senden

Für ein Modell, das laut Katalog Chat Completions unterstützt:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Antworte mit dem Namen des aktiven Modells."}
    ],
    "stream": false
  }'

Für ein Responses-kompatibles Coding-Modell:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Antworte mit dem Namen des aktiven Modells.",
    "stream": false
  }'

Verwenden Sie exakt die Modell-ID aus dem Live-Katalog. model_not_found bedeutet meist, dass Schlüssel oder Gruppe keinen Zugriff haben. Eine andere Groß- und Kleinschreibung behebt das in der Regel nicht.

Streaming gesondert validieren

Ein erfolgreicher Aufruf ohne Streaming genügt nicht, wenn die Anwendung inkrementelle Ausgabe benötigt. Wiederholen Sie die Anfrage mit "stream": true, prüfen Sie den schrittweisen Eingang der Events und stellen Sie sicher, dass der Client nicht erst die vollständige Antwort puffert.

Bei langsamem Streaming sollten Sie getrennt betrachten:

• Zeit für Authentifizierung und Routenauswahl;
• Zeit bis zu den Upstream-Response-Headern;
• Zeit bis zum ersten wirksamen Text-, Reasoning- oder Tool-Event;
• Generierungsgeschwindigkeit nach Beginn der sichtbaren Ausgabe.

Die Nutzungsprotokolle von Modelflare erfassen diese Zeiten pro Anfrage, ohne Prompts, Antworttexte, rohe Request-Bodies, API-Schlüssel, E-Mail-Adressen oder Klartext-IP-Adressen zu speichern.

Checkliste für den Produktivwechsel

• Bewahren Sie den API-Schlüssel in einem Secret Store oder einer Umgebungsvariable auf.
• Setzen Sie die Base URL fest auf https://modelflare.dev/v1.
• Verwenden Sie ein Modell, das den gewählten Endpunkt ausdrücklich unterstützt.
• Testen Sie Streaming und Nicht-Streaming unabhängig voneinander.
• Prüfen Sie bei Bedarf Tools, strukturierte Ausgabe, Reasoning-Steuerung und multimodale Eingaben.
• Erhalten Sie explizite Werte wie 0 und false, wenn sie semantisch relevant sind.
• Richten Sie Timeouts nach der echten Arbeitslast und nicht nach einem kurzen Health-Check aus.
• Kontrollieren Sie nach der Umstellung Status, Latenz, Token-Nutzung, gewählte Gruppe und Kosten.

Ist die Protokollgrenze geprüft, kann der Client seinen bestehenden Anfrageablauf meist beibehalten. Modelflare übernimmt dahinter Modellzugriff, Routing-Richtlinien und Transparenz auf Anfrageebene.