OpenAI-kompatible API: Basis-URL ändern

Was OpenAI-Kompatibilität abdeckt, wie Sie einen bestehenden Client auf Modelflare umstellen und welche Grenzen Sie vor dem Produktivbetrieb prüfen sollten.

OpenAI-kompatible API: Basis-URL ändern

Mit einer OpenAI-kompatiblen API behält ein bestehender Client den vertrauten Authentifizierungs-Header, die JSON-Struktur der Anfragen und das Streaming-Muster bei, während der Traffic an ein anderes Gateway geht. Oft genügt es, Basis-URL und API-Schlüssel auszutauschen. Kompatibilität bleibt dennoch ein Protokollvertrag – keine Zusage, dass jedes Modell jeden Endpunkt oder jedes anbieterspezifische Feld unterstützt.

Dieser Leitfaden beschreibt den sicheren Migrationsweg für Anwendungen, Skripte und KI-Tools, die bereits eine API im OpenAI-Stil verwenden.

Was OpenAI-Kompatibilität tatsächlich umfasst

Die am besten wiederverwendbaren Teile des Vertrags sind:

  • Bearer-Token-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.
  • Vertraute Anfragefelder wie model, messages, input, stream sowie Tool-Definitionen, sofern das gewählte Protokoll sie unterstützt.

Kompatibilität bedeutet nicht, dass sich ein Modell beliebig zwischen Chat Completions und Responses verschieben lässt. Ein Modell kann nur über ein einziges geprüftes Protokoll bereitgestellt sein. Anbieterspezifische Felder für Reasoning, Suche oder multimodale Eingaben müssen unter Umständen unverändert durchgereicht werden, statt im Gateway übersetzt zu werden.

Betrachten Sie den aktuellen Katalog unter Modelle & Preise als maßgebliche Quelle für das Modell, die Gruppe und das API-Format, die Sie verwenden möchten.

Migration vorbereiten

Bevor Sie Anwendungscode ändern:

  1. Erstellen Sie unter API-Schlüssel einen eigenen Schlüssel, statt einen persönlichen oder für eine andere Integration genutzten Schlüssel wiederzuverwenden.
  2. Wählen Sie eine primäre Modellgruppe, die Zugriff auf das gewünschte Modell hat.
  3. Fügen Sie geordnete Fallback-Gruppen nur hinzu, wenn sie dieses Modell ebenfalls unterstützen und zu denselben Kosten- und Zuverlässigkeitsvorgaben passen.
  4. Notieren Sie den aktuellen Endpunkt, die Modell-ID, die Streaming-Einstellung und die Tool-Nutzung, damit Sie das Verhalten vor und nach der Umstellung vergleichen können.

Die kanonische OpenAI-kompatible Basis-URL von Modelflare lautet:

https://modelflare.dev/v1

Die meisten SDKs erwarten, dass die Basis-URL mit /v1 endet, und hängen /chat/completions oder /responses selbst an. Prüfen Sie die Dokumentation des Clients, bevor Sie ein zweites Endpunkt-Suffix ergänzen.

Zuerst Authentifizierung und Modellzugriff prüfen

Speichern Sie den Schlüssel in einer Umgebungsvariable statt 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 belegt, dass Hostname, TLS-Verbindung und Schlüssel gültig sind. Sie belegt noch nicht, dass ein bestimmtes Anfrageformat für jedes zurückgegebene Modell gültig ist. Der nächste Test muss deshalb den vorgesehenen Endpunkt verwenden.

Eine Anfrage mit dem vorgesehenen Protokoll senden

Für ein Chat-Completions-Modell, das für dieses Format als kompatibel ausgewiesen ist:

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": "Reply with the active model name."}
    ],
    "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": "Reply with the active model name.",
    "stream": false
  }'

Verwenden Sie exakt die Modell-ID aus dem Live-Katalog. Das Ergebnis model_not_found bedeutet meist, dass der gewählte Schlüssel oder die Gruppe keinen Zugriff auf dieses Modell hat – eine andere Groß- und Kleinschreibung behebt die Anfrage in der Regel nicht.

Streaming gesondert validieren

Ein Erfolg ohne Streaming reicht für eine Anwendung, die auf Streaming angewiesen ist, nicht aus. Wiederholen Sie die Anfrage mit "stream": true, prüfen Sie, ob die Events schrittweise eintreffen, und stellen Sie sicher, dass der Client nicht die vollständige Antwort puffert, bevor er sie darstellt.

Trennen Sie bei der Diagnose eines langsamen Streams:

  • die Zeit für Authentifizierung und Routenauswahl;
  • die Zeit bis zu den Antwort-Headern des Dienstanbieters;
  • die Zeit bis zum ersten effektiven Inhalts- oder Tool-Delta;
  • den Generierungsdurchsatz nach Beginn der sichtbaren Ausgabe.

Die Nutzungsprotokolle von Modelflare bewahren dafür Zeitmetadaten pro Anfrage auf, ohne Prompts, Antworttexte, rohe Anfrageinhalte, API-Schlüssel, E-Mail-Adressen oder Klartext-IP-Adressen zu speichern.

Checkliste für die Produktivumstellung

  • Bewahren Sie den API-Schlüssel in einem Secret Store oder einer Umgebungsvariable auf.
  • Legen Sie die Basis-URL fest auf https://modelflare.dev/v1.
  • Verwenden Sie ein Modell, das den gewählten Endpunkt ausdrücklich unterstützt.
  • Testen Sie den Betrieb mit und ohne Streaming unabhängig voneinander.
  • Testen Sie Tools, strukturierte Ausgabe, Reasoning-Steuerung und multimodale Eingaben, sofern die Anwendung sie nutzt.
  • Behalten Sie explizite Werte wie 0 oder false bei, wenn sie in der Anfrage des Clients eine Bedeutung tragen.
  • Legen Sie Client-Timeouts für die echte Arbeitslast fest, nicht für einen kurzen Health-Check-Prompt.
  • Prüfen Sie nach der Umstellung in den Nutzungsprotokollen Status, Latenz, Token-Nutzung, ausgewählte Gruppe und Kosten.

Sobald die Protokollgrenze geprüft ist, kann der Client seinen bestehenden Anfrageablauf in der Regel beibehalten, während Modelflare hinter dem kompatiblen Endpunkt Modellzugriff, Routing-Richtlinie und Transparenz pro Anfrage bereitstellt.

Mehr über die Betriebsebene hinter diesem Endpunkt erfahren Sie unter Was ist ein KI-API-Gateway?. Kann der Client mehr als ein OpenAI-Format verwenden, vergleichen Sie Responses API oder Chat Completions, bevor Sie Pfade ändern.