Wenn Ihre App bereits eine OpenAI-kompatible API verwendet, sollte der Wechsel zu Flatkey nicht mit einem Rewrite beginnen. Der kontrollierte Weg ist kleiner: Holen Sie sich einen Flatkey-Schlüssel, richten Sie Ihr OpenAI-kompatibles SDK auf https://router.flatkey.ai/v1 aus, wählen Sie eine Modell-ID aus dem Flatkey-Katalog und prüfen Sie die erste Anfrage in Logs, Kontingenten und Abrechnung, bevor Sie echten Traffic senden.
Der praktische Nutzen einer OpenAI-kompatiblen API besteht genau darin. Sie ermöglicht es einem Team, dasselbe mentale Modell für gängige Anfragen beizubehalten, während der Provider-Zugriff hinter ein einziges Gateway verlagert wird. Flatkeys öffentliche Produktkommunikation ist auf diese Bewegung ausgerichtet: ein API-Schlüssel, eine Basis-URL, klare Preise, einheitliche Abrechnung und ein Dashboard für Schlüssel, Nutzung und Routing.
Dieser Leitfaden zeigt das Migrations-Runbook. Er behandelt die Änderung der Basis-URL, SDK-Beispiele, das Mapping von Modell-IDs, Smoke-Tests, Endpoint-Prüfungen, die Überprüfung der Nutzungslogs, die Einrichtung von Kontingenten, die Abrechnungsprüfung und das Rollback. Verwenden Sie ihn, wenn Sie einen bestehenden Workflow im Chat-Completions-Stil zu Flatkey migrieren oder einen Multi-Model-Stack hinter einem einzigen Endpunkt einer OpenAI-kompatiblen API standardisieren.
Quick Answer: Was ändert sich bei einer OpenAI-kompatiblen API-Migration?
Für die meisten bestehenden OpenAI-kompatiblen Chat-Clients ist die erste Migration eine Konfigurationsänderung, kein Rewrite der Anwendung.
| Einstellung | Vorher | Mit Flatkey |
|---|---|---|
| API-Schlüssel | Anbieterspezifischer OpenAI-, Gemini-, DeepSeek- oder Proxy-Schlüssel | Flatkey API key |
| Base URL | Standard des Anbieters oder eine andere OpenAI-kompatible Base URL | https://router.flatkey.ai/v1 |
| Chat-Endpunkt | /v1/chat/completions |
/v1/chat/completions über Flatkey |
| Modell | Bestehende Modell-ID des Anbieters | Flatkey Modell-ID, ausgewählt aus Preisübersicht/Dashboard |
| Validierung | Nur eine erfolgreiche Antwort | Antwort + Nutzungsprotokoll + Kosten + Kontingent + Rollback |
Das wichtige Wort ist „kompatibel“. Eine OpenAI compatible API garantiert nicht, dass jeder Anbieter, jedes Modell, jeder Endpunkt und jeder Parameter exakt wie OpenAI funktioniert. Es bedeutet, dass die API dem OpenAI-Anfrage- und Antwortmuster weit genug folgt, damit gängige Client-Aufrufe funktionieren, wenn Base URL, Schlüssel und Modell korrekt sind. Ihre Migrations-Checkliste sollte die genauen Funktionen nachweisen, die Ihre App verwendet.
Warum OpenAI-kompatible Endpunkte zur Migrationsschicht werden
Die Suchergebnisse für OpenAI compatible API bestehen größtenteils aus offiziellen Referenzen, Anbieter-Dokumentationen, Plugins, Dokumentationen lokaler Server und Fragen aus der Community. Das ergibt Sinn. Entwickler fragen nicht nur „was ist kompatibel?“ Sie versuchen, Code zwischen Modellanbietern zu verschieben, ohne jede Aufrufstelle zu ändern.
Die Gemini-Dokumentation von Google zeigt Beispiele für die OpenAI-Bibliothek, die eine Gemini-OpenAI-kompatible Base URL setzen und Chat Completions aufrufen. Die offizielle API-Dokumentation von DeepSeek zeigt OpenAI-SDK-Beispiele mit DeepSeeks Base URL und Modell-IDs wie deepseek-chat und deepseek-reasoner. Das Muster ist klar: Viele Anbieter holen Entwickler dort ab, wo ihre bestehenden SDKs bereits sind.
Flatkey nutzt dieselbe Migrationsidee für ein anderes Ziel. Statt die OpenAI compatible API eines Anbieters auf ein einzelnes Anbieter-Konto zu richten, bietet Flatkey Teams eine einzige OpenAI-kompatible Base URL für Multi-Model-Zugriff, einheitliche Abrechnung und Transparenz im Dashboard.
Schritt 1: Inventarisieren Sie den Client, den Sie bereits haben
Bevor Sie die Basis-URL ändern, schreiben Sie auf, was Ihre aktuelle App tatsächlich verwendet. Eine saubere OpenAI-kompatible API-Migration beginnt mit der live gesendeten Call-Struktur, nicht mit einer neuen Beispiel-App.
| Prüfung | Was protokolliert werden soll |
|---|---|
| SDK | Python, Node, direktes HTTP, LangChain, LiteLLM, Vercel AI SDK oder ein anderes Wrapper. |
| Endpunkt | Chat Completions, Responses, Embeddings, Bilder, Video oder ein provider-nativer Endpunkt. |
| Modell-ID | Exakter String, der in der Produktion verwendet wird, sowie alle Fallback-Modelle. |
| Nachrichtenstruktur | System-Prompts, Developer-Nachrichten, Tool-Nachrichten, multimodale Inhalte oder nur reiner Text. |
| Parameter | Streaming, Temperatur, max. Tokens, Tool-Aufrufe, JSON-Ausgabe, Antwortformat, Seed, Timeout, Wiederholungen. |
| Observability | Wo Sie heute Latenz, Token-Nutzung, Request-IDs, Fehler und Kosten sehen. |
| Rollback | Wie schnell Sie den alten API-Key/die alte Basis-URL/das alte Modell wiederherstellen können. |
Dieses Inventar hält die Migration ehrlich. Wenn Ihre App nur einfache Chat-Nachrichten sendet, kann der erste Flatkey-Test klein bleiben. Wenn Ihre App von Streaming, Tool-Aufrufen, JSON-Modus, Bildern, Video oder der Responses API abhängt, behandeln Sie jedes Feature als separaten Smoke-Test.
Schritt 2: Lege die Basis-URL hinter eine Config-Schicht
Verteile die neue OpenAI-kompatible Basis-URL nicht über die gesamte Codebasis. Lege sie in einer einzigen Umgebungsvariable oder in einer SDK-Fabrik ab.
Empfohlene Umgebungsvariablen:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Die Verwendung von OPENAI_BASE_URL ist oft praktisch, weil viele SDK-Wrapper dieses Muster bereits unterstützen. Die Verwendung von FLATKEY_API_KEY und FLATKEY_MODEL hält die neuen Anmeldedaten und die Modellauswahl explizit.
Hier passt Flatkey zur Suchintention openai compatible base url. Die Migration sollte in einem einzigen Diff überprüfbar sein: Basis-URL, Schlüssel, Modell und Verifizierungsschritte.
Schritt 3: Einen Curl-Smoke-Test ausführen
Beginnen Sie mit einer direkten HTTP-Anfrage, bevor Sie Ihre Anwendung ändern. So lassen sich Probleme mit dem Key, der Base-URL, dem Endpoint und der Modell-ID eingrenzen.
Nur Vorlage: Der Prüfer sollte mit einem gültigen Flatkey-Key und einer bestätigten Modell-ID für den Veröffentlichungstag ausführen.
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Antworte mit einem Satz, der bestätigt, dass dieser Flatkey-Smoke-Test funktioniert hat."
}
]
}'Ein nützlicher Smoke-Test beweist mehr als 200 OK. Bei einer OpenAI-kompatiblen API-Migration prüfen Sie:
- Die Antwort enthält eine nutzbare Assistant-Nachricht.
- Der Modellname ist der, den Sie testen wollten.
- Die Nutzung erscheint im Flatkey-Dashboard oder in den Nutzungsprotokollen.
- Token-Anzahl und Kosten sind für die Rechnungsprüfung ausreichend sichtbar.
- Fehlermeldungen sind verständlich, wenn die Modell-ID oder der Key falsch ist.
- Die alte Base-URL und das alte Modell lassen sich bei Bedarf schnell wiederherstellen.
Schritt 4: Die Python-OpenAI-SDK-Konfiguration ändern
Wenn Ihre Python-App das OpenAI SDK bereits verwendet, halten Sie die Client-Erstellung zentralisiert.
Nur Vorlage: Der Prüfer sollte dies vor der Veröffentlichung ausführen.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Bestätigen Sie, dass diese OpenAI-kompatible API-Anfrage über Flatkey weitergeleitet wird.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)Das für Python wichtige Detail ist base_url. Bei einer sauberen Migration zu einer OpenAI-kompatiblen API sollte der Anwendungscode nicht wissen, ob die Basis-URL direkt auf OpenAI, einen kompatiblen Endpunkt eines Anbieters oder auf Flatkey zeigt. Er sollte den gemeinsamen Client aufrufen und die Konfiguration den Pfad auswählen lassen.
Schritt 5: Node-OpenAI-SDK-Konfiguration ändern
Für Node-Apps verwendet die entsprechende Konfiguration baseURL.
Nur Vorlage: Der Prüfer sollte vor der Veröffentlichung ausführen.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Bestätigen Sie, dass diese OpenAI-kompatible API-Anfrage über Flatkey geroutet wird.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Dies ist dasselbe Migrationsmuster, das in den Dokumentationen der Anbieter zu sehen ist: SDK beibehalten, eine andere Basis-URL festlegen, einen kompatiblen API-Schlüssel angeben und eine Modell-ID wählen, die auf der Zielplattform vorhanden ist.
Schritt 6: Modell-IDs bewusst zuordnen
Der Modellstring ist der Punkt, an dem viele Migrationen OpenAI-kompatibler APIs scheitern. Eine Basis-URL kann kompatibel sein, während Modell-IDs weiterhin anbieterspezifisch bleiben.
Nehmen Sie nicht an:
- Dass Ihr alter Modellname in Flatkey existiert.
- Dass ein Modellalias eines Anbieters hinter einem Gateway auf dieselbe Version verweist.
- Dass jedes kompatible Modell dieselbe Endpunktfamilie unterstützt.
- Dass ein Modell, das für Chat funktioniert, auch für Vision, Tools, Bilder, Video oder Responses funktioniert.
Verwenden Sie stattdessen diese Zuordnungstabelle vor dem ersten Test auf Anwendungsebene:
| Aktuelle App-Nutzung | Flatkey-Prüfung |
|---|---|
| Text-Chat | Wählen Sie ein Flatkey-Modell, das den OpenAI-Chat-Endpunkt unterstützt. |
| Streaming-Chat | Testen Sie Streaming separat mit demselben Prompt und demselben Timeout-Budget. |
| Tool-/Funktionsaufrufe | Stellen Sie sicher, dass das ausgewählte Modell und der Endpunkt die von Ihrer App gesendete Tool-Call-Struktur unterstützen. |
| JSON-Ausgabe | Testen Sie Ihr exaktes response_format oder Ihr strukturiertes Ausgabe-Pattern. |
| Vision/Bildeingabe | Bestätigen Sie, dass das ausgewählte Modell das Bild-Eingabeformat akzeptiert, das Ihr SDK sendet. |
| Responses API | Bestätigen Sie, dass der Flatkey-Endpunkt/das Modell /v1/responses für Ihren Anwendungsfall unterstützt. |
| Bild- oder Videogenerierung | Behandeln Sie dies als separate Endpunkt-Migration und nicht als Chat-Completions-Migration. |
Flatkeys Preissnapshot vom 11. Juni 2026 zeigte Endpunktfamilien für OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini, Bildgenerierung und OpenAI Video. Das ist ein nützlicher Nachweis für Reviewer, aber der Artikel sollte die Leser dennoch dazu anhalten, das exakte Modell und die Funktion zu bestätigen, die sie am Veröffentlichungstag verwenden möchten.
Schritt 7: Protokolle, Quoten und Abrechnung überprüfen
Eine erfolgreiche Antwort der OpenAI-kompatiblen API ist nur der erste Prüfpunkt. Der Grund, über Flatkey zu migrieren, ist nicht nur die Form der Anfrage; es ist die Betriebsebene rund um den Modellzugriff.
Nach dem Smoke-Test überprüfen:
| Bereich | Was zu prüfen ist |
|---|---|
| Nutzungsprotokoll | Die Anfrage erscheint mit Zeitstempel, Modell, Token-Nutzung, Status und ggf. Fehlerdetails. |
| Abrechnung | Die Kosten sind sichtbar und entsprechen dem erwarteten Modell-/Preismodell. |
| Kontingent | Für den neuen Schlüssel oder den Test-Route kann vor einem breiteren Rollout ein kleines Kontingent gesetzt werden. |
| Routing | Die Anfrage wird über den vorgesehenen Flatkey-Pfad geleitet, nicht über eine veraltete direkte Provider-Konfiguration. |
| Fehlerverhalten | Fehler bei schlechtem Schlüssel, falschem Modell und nicht unterstützten Parametern sind klar genug für den Support. |
| Rollback | Das Wiederherstellen der vorherigen Base-URL/des vorherigen Modells funktioniert ohne Codeänderungen. |
Hier wird ein OpenAI-kompatibles API-Gateway nützlicher als ein reiner Provider-Endpunkt. Die Änderung der Base-URL sollte zu besserer Sichtbarkeit führen, nicht nur zu einem anderen Upstream.
Schritt 8: In Etappen ausrollen
Verschieben Sie nicht alle Workflows auf einmal. Verwenden Sie einen gestaffelten Rollout:
- Führen Sie einen direkten curl-Smoke-Test aus.
- Führen Sie einen SDK-Smoke-Test lokal oder in Staging aus.
- Spielen Sie einen kleinen bekannten Prompt-Satz ab und vergleichen Sie die Ausgabeform.
- Aktivieren Sie Streaming oder erweiterte Parameter erst, nachdem der grundlegende Aufruf erfolgreich ist.
- Setzen Sie ein niedriges Kontingent für den Testschlüssel.
- Senden Sie einen kleinen Prozentsatz des nicht kritischen Traffics.
- Vergleichen Sie Fehler, Latenz, Token-Nutzung und Kosten.
- Erhöhen Sie den Traffic erst, nachdem Logs und Abrechnung den Erwartungen entsprechen.
Dieser Ablauf hält das Versprechen einer OpenAI kompatiblen API an die Produktionsrealität gebunden. Kompatibilität ist kein Slogan; sie ist ein Testergebnis für die Aufrufe, die Ihre App tatsächlich sendet.
Migrations-Checkliste
Verwenden Sie dies als Asset für die Veröffentlichungsseite.
| Schritt | Erledigt? | Notizen |
|---|---|---|
| Aktuelles SDK und Endpunkt sind dokumentiert | Python, Node, HTTP, Wrapper, Chat, Responses, Bild, Video usw. | |
| Flatkey-Schlüssel ist erstellt | Verwenden Sie nach Möglichkeit einen separaten Testschlüssel. | |
| Basis-URL ist zentralisiert | https://router.flatkey.ai/v1 sollte in der Konfiguration stehen, nicht verstreut im Code. |
|
| Modell-ID wird von Flatkey ausgewählt | Bestätigen Sie die Modell-ID für den Veröffentlichungstag über Preise oder das Dashboard. | |
| Curl-Smoke-Test besteht | Die Vorlage muss vor der Veröffentlichung von einem Prüfer getestet werden. | |
| Python- oder Node-SDK-Smoke-Test besteht | Verwenden Sie das SDK, das Ihre App tatsächlich ausführt. | |
| Streaming-/Tool-/JSON-/Vision-Funktionen sind getestet | Testen Sie nur die Funktionen, die Sie verwenden. | |
| Nutzungsprotokoll ist sichtbar | Bestätigen Sie Modell, Status, Tokens und Fehler im Dashboard. | |
| Abrechnung und Preiseinheit sind geprüft | Gehen Sie nicht davon aus, dass die Preiseinheiten der Anbieter identisch sind. | |
| Kontingentlimit ist festgelegt | Halten Sie den Migrationsverkehr begrenzt. | |
| Rollback-Umgebungsvariablen sind bereit | Alte Basis-URL und altes Modell können ohne Codeänderungen wiederhergestellt werden. |
Häufige Fehler
Der häufigste Migrationsfehler bei einer OpenAI-kompatiblen API besteht darin, nur die Base-URL zu ändern und anzunehmen, dass jedes andere Detail identisch ist. Vermeiden Sie diese Fallstricke:
- Die Flatkey-Base-URL in mehreren Dateien fest zu kodieren.
- Eine alte Provider-Model-ID beizubehalten, die Flatkey nicht weiterleitet.
- Nur Nicht-Streaming zu testen, obwohl in der Produktion Streaming verwendet wird.
- Tests für Tool-Calls oder JSON-Ausgaben zu überspringen.
- Bild-/Video-Endpunkte so zu verschieben, als wären sie Chat-Completions-Endpunkte.
- Zu vergessen, Retries, Timeout-Budgets und Fehlerparsing zu aktualisieren.
- Die Migration für abgeschlossen zu erklären, bevor Nutzung und Abrechnung sichtbar sind.
Flatkey reduziert die Komplexität bei Provider-Konten und Routing, aber es ersetzt nicht die Notwendigkeit eines sorgfältigen Migrationstests.
Wann Flatkey gut passt
Flatkey passt gut, wenn Ihr Team eine einzige OpenAI-kompatible API-Basis-URL für den Zugriff auf mehrere Modelle möchte, statt separate Provider-Konten, Schlüssel, Abrechnung und Routing-Prüfungen zu verwalten.
Verwenden Sie Flatkey, wenn:
- Ihre App bereits ein OpenAI-kompatibles SDK verwendet.
- Sie einen Schlüssel für Modelle über Anbieter wie GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0 und GPT Image hinweg möchten.
- Sie Nutzung, Abrechnung, Schlüssel und Routing in einem Dashboard sehen möchten.
- Sie Kontingentgrenzen wünschen, bevor der Traffic ansteigt.
- Sie möchten, dass Modellwechsel und Load-Balancing-Verhalten von der Gateway-Ebene übernommen werden.
- Sie möchten, dass der Migrationspfad „Basis-URL ändern, Modell verifizieren, Nutzung überwachen“ lautet statt „die Modellintegration neu schreiben“.
Verwenden Sie ein direktes Provider-Konto oder einen selbst gehosteten Proxy, wenn Sie anbieterspezifische Verträge, vollständig benutzerdefinierte Routing-Logik oder eine gatewayseitige Steuerung innerhalb Ihrer eigenen Infrastruktur benötigen.
FAQ
Ist eine OpenAI-kompatible API dasselbe wie OpenAI?
Nein. Eine OpenAI-kompatible API folgt für unterstützte Endpunkte dem OpenAI-ähnlichen Anfrage- und Antwortmuster, aber Anbieter, Modell-IDs, Authentifizierung, Funktionsunterstützung, Preise und Fehlerverhalten können sich unterscheiden.
Muss ich mein SDK ersetzen, um Flatkey zu verwenden?
Normalerweise nicht bei gängigen Chat-Completions-Migrationen. Wenn Ihr SDK eine benutzerdefinierte Base URL unterstützt, können Sie das SDK oft beibehalten und nur die Konfiguration ändern. Das ist der zentrale Vorteil einer Migration zu einer OpenAI-kompatiblen API.
Was ist die OpenAI-kompatible Base URL von Flatkey?
Verwenden Sie https://router.flatkey.ai/v1 als OpenAI-kompatible Base URL. Für Chat Completions lautet der vollständige Endpunkt https://router.flatkey.ai/v1/chat/completions.
Kann ich meinen bestehenden Modellnamen beibehalten?
Nur wenn diese Modell-ID über Flatkey verfügbar und unterstützt wird. Prüfen Sie die Preise oder das Dashboard und testen Sie dann die exakte Modell-ID vor dem Rollout.
Sollte ich zuerst Chat Completions oder Responses migrieren?
Migrieren Sie den Endpunkt, den Ihre bestehende App verwendet. Bestehende Chat-Completions-Apps können mit /v1/chat/completions beginnen. Wenn Ihre App die Responses API verwendet, testen Sie /v1/responses separat und bestätigen Sie, dass das ausgewählte Modell die Funktionen unterstützt, die Sie benötigen.
Wie rolle ich zurück?
Behalten Sie die alte Base URL, den API-Schlüssel und das Modell in der Konfiguration, bis Flatkey-Logs, Kosten, Kontingent und Anwendungsverhalten überprüft sind. Der Rollback sollte eine Änderung der Umgebungsvariable sein, kein Code-Rewrite.
Erhalten Sie einen Schlüssel
Wenn Sie bereits eine App rund um eine OpenAI-kompatible API gebaut haben, hält Flatkey die Migration klein: Schlüssel holen, Basis-URL ändern, ein Modell auswählen, den Smoke-Test ausführen und die Nutzung in einem Dashboard überwachen.
Holen Sie sich einen Schlüssel, und verwenden Sie dann https://router.flatkey.ai/v1 als Basis-URL für Ihren ersten Flatkey-Migrationstest.