„OpenAI-kompatibel“ ist fast zu einem allgemeinen Verkaufsargument für LLM-Dienste geworden: Base URL austauschen, und das bestehende OpenAI SDK ruft ein Modell eines anderen Anbieters auf. Es klingt nach einer Zeile Konfiguration, doch bei der Migration treten häufig 404, Parameterfehler, abgebrochene Streams und abweichende Tool-Call-Formate auf. Der Grund ist einfach: Kompatibilität deckt meist nur die gängigsten Schnittstellen ab, nicht alle Fähigkeiten.
Dieser Artikel klärt die Grenzen der Kompatibilität, die korrekte Schreibweise der Base URL, die SDK-Konfiguration, Parameterunterschiede und die Migrationsschritte, damit Sie Modelle oder Anbieter wechseln können, ohne den Geschäftscode umzubauen.
Hinweis: OpenAI ist eine Marke ihres jeweiligen Inhabers; dieser Artikel steht in keiner Verbindung zu den genannten Anbietern. Der Kompatibilitätsumfang richtet sich nach der jeweiligen Dokumentation, Modelle und Preise nach den Modellpreisen auf dieser Website.
1. Welche Ebene „kompatibel“ tatsächlich abdeckt
Eine OpenAI-kompatible API verwendet üblicherweise dieselben HTTP-Pfade, Request-Felder und Antwortstrukturen. Der Grad der Kompatibilität unterscheidet sich jedoch stark:
| Schnittstelle | Zweck | Übliche Kompatibilität |
|---|---|---|
/v1/chat/completions |
Dialog und Textgenerierung | Am verbreitetsten, Grundfelder meist unterstützt |
/v1/embeddings |
Textvektoren | Verbreitet, Vektordimension prüfen |
/v1/models |
Modellliste | Teils nur teilweise oder gar nicht zurückgegeben |
/v1/images/generations |
Bildgenerierung | Anbieterabhängig |
/v1/audio/transcriptions |
Audiotranskription | Anbieterabhängig |
/v1/responses |
Neuere Responses-Schnittstelle | Unterschiedlich, vor Migration prüfen |
„Kompatibel“ ist also nicht „vollständig gleichwertig“. Mindeststandard für die Anbindung ist, dass /v1/chat/completions zuverlässig antwortet; hängt das Geschäft von Tool-Aufrufen, strukturierter Ausgabe oder Multimodalität ab, muss jedes dieser Felder einzeln geprüft werden, nicht nur die Werbeseite.
2. Die Base URL richtig schreiben
Das SDK hängt automatisch Pfade wie /chat/completions an die Base URL an. Daher endet die Base URL üblicherweise bei /v1 und nicht beim konkreten Endpunkt. Gängige Formen:
| Schreibweise | Üblich | Erläuterung |
|---|---|---|
https://api.example.com/v1 |
Am häufigsten | SDK hängt /chat/completions an |
https://api.example.com/openai/v1 |
Bei manchen Gateways | Pfadpräfix gibt der Anbieter vor |
https://api.example.com/v1/chat/completions |
Falsch | Erzeugt doppelten Pfad und 404 |
https://api.example.com |
Implementierungsabhängig | Manche Dienste ergänzen /v1, nicht voraussetzen |
Drei Details:
- Keine mehrfachen Schrägstriche am Ende anhängen, sonst entsteht
//chat/completions. - Zwischen „Konsolenadresse“ und „API-Adresse“ unterscheiden; erstere ist meist keine gültige Base URL.
- Wenn das Beispiel des Anbieters direkt funktioniert, übernehmen Sie es unverändert und schreiben Sie den Pfad nicht um.
3. SDK-Anbindung: drei gleichwertige Schreibweisen
Python mit dem offiziellen SDK:
from openai import OpenAI
client = OpenAI(
api_key="sk-dein-schluessel",
base_url="https://api.example.com/v1",
)
resp = client.chat.completions.create(
model="dein-modellname",
messages=[{"role": "user", "content": "Antworte nur mit OK"}],
)
print(resp.choices[0].message.content)
Node SDK:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
baseURL: "https://api.example.com/v1",
});
const resp = await client.chat.completions.create({
model: "dein-modellname",
messages: [{ role: "user", content: "Antworte nur mit OK" }],
});
console.log(resp.choices[0].message.content);
Alternativ über Umgebungsvariablen, damit Adresse und Key nicht im Code stehen:
export OPENAI_API_KEY="sk-dein-schluessel"
export OPENAI_BASE_URL="https://api.example.com/v1"
Das offizielle SDK liest OPENAI_BASE_URL üblicherweise, doch Name und Verhalten können je Sprache und Version abweichen; maßgeblich ist die Dokumentation des verwendeten SDK. In der Produktion gehört die Base URL in einen Konfigurationsdienst und der Key in einen Secret-Manager.
4. Parameterkompatibilität: hier lauern die meisten Fallen
Ein funktionierender Basis-Dialog bedeutet nicht, dass alle Parameter unterstützt werden. Vor der Migration prüfen:
| Parameter | Häufige Abweichung |
|---|---|
model |
Muss der beim Anbieter hinterlegte Name sein, nicht der offizielle Modellname |
max_tokens |
Neuere Modelle nutzen teils max_completion_tokens; das alte Feld wird eventuell abgelehnt oder ignoriert |
temperature / top_p |
Reasoning-Modelle ignorieren oder fixieren den Wert eventuell |
stream |
Meist unterstützt, die Struktur der Stream-Events kann aber abweichen |
tools / tool_choice |
Stark unterschiedlich; parallel_tool_calls ist nicht immer verfügbar |
response_format |
json_object ist verbreitet, json_schema unterschiedlich unterstützt |
seed / logprobs / n |
Viele kompatible Dienste unterstützen sie nicht und werfen eventuell einen Fehler |
reasoning_effort |
Nur bei manchen Reasoning-Modellen, Bedeutung kann abweichen |
Bewährt ist ein „minimaler Parametersatz“, der nur die wirklich benötigten Felder enthält; nicht unterstützte Parameter werden per Konfiguration deaktiviert und nicht fest im Request verdrahtet.
5. Schritte der Migration von der offiziellen API
In dieser Reihenfolge lässt sich das Risiko klein halten:
- Aufrufstellen inventarisieren: Alle Dienste, Skripte und Cronjobs auflisten, die das OpenAI SDK verwenden.
- Abhängige Fähigkeiten erfassen: Wo werden Dialog, Streaming, Tool-Aufrufe, strukturierte Ausgabe, Embeddings und Multimodalität eingesetzt?
- Neuen Key beantragen und Budget setzen: Für die Migration einen eigenen Key mit Obergrenzen und Warnungen anlegen.
- Base URL umstellen: Bevorzugt über Umgebungsvariablen oder Konfiguration, nicht durch Änderung des Geschäftscodes.
- Smoke-Test ausführen: Je einen Request mit curl und SDK senden und Adresse, Key und Modellname bestätigen.
- Regressionsstichproben ausführen: 30–100 echte Requests vorbereiten und Ausgabequalität, Latenz, Fehlercodes und Token-Verbrauch vergleichen.
- Schrittweise Traffic verlagern: Zuerst einen unkritischen Bereich umstellen, eine Woche beobachten, dann ausweiten; einen Ein-Klick-Rollback bereithalten.
Migration ist nicht „Adresse tauschen und fertig“. Mit einem neuen Modell können sich Ausgabestil, Kontextlänge und Erfolgsquote von Tool-Aufrufen ändern; ein Evaluationssatz ist verlässlicher als das Gefühl.
6. Häufige Fehler und Fehlersuche
| Fehler | Häufige Ursache | Behandlung |
|---|---|---|
| 401 – Authentifizierungsfehler | Key falsch, abgelaufen oder nicht mitgesendet | Header und Key auf überflüssige Zeichen prüfen |
| 403 Forbidden | Key ohne Modellrecht oder Risikokontrolle ausgelöst | Modellrechte und Kontostatus prüfen |
| 404 Not Found | Base URL falsch | /chat/completions entfernen und klären, ob /v1 nötig ist |
| 400 Bad Request | Parameter nicht unterstützt oder Formatfehler | Parameter einzeln ausschließen, auf minimalen Body zurückgehen |
| 429 Too Many Requests | Parallelität oder Kontingent überschritten | Parallelität senken, exponentielles Backoff |
| 500 / 502 / 503 | Upstream- oder Gateway-Störung | Wiederholen und Request-ID erfassen, bei anhaltendem Fehler Ersatzkanal |
| Stream bricht ab | Proxy-Pufferung, Timeout oder Netzschwankung | Proxy-Pufferung abschalten, Timeout und Heartbeat sinnvoll setzen |
Für die Fehlersuche den Original-Request aufbewahren: URL, Header (Key maskiert), Body, Statuscode und Antwortkörper. Mit nur „der Aufruf ist fehlgeschlagen“ lässt sich selten etwas finden.
7. Streaming, Tool-Aufrufe und Multimodalität: die echten Unterschiede
- Streaming: Kompatible Schnittstellen liefern üblicherweise Server-Sent Events, beginnend mit
data:und endend mit[DONE]. Inkrementelle Tool-Call-Felder und ob Usage-Statistiken im Stream mitkommen, sind jedoch nicht einheitlich. Vor dem Aktivieren der Statistik beim Anbieter prüfen. - Tool-Aufrufe: Funktionsnamen und JSON-Struktur der Parameter sind weitgehend gleich, aber parallele Aufrufe, Strict-Modus und Denkprozess-Felder können fehlen. Bei komplexen Agenten zuerst eine echte Tool-Kette testen.
- Strukturierte Ausgabe:
json_objectist meist verfügbar, JSON-Schema-Constraints nicht unbedingt. Downstream weiterhin parsen und validieren; nicht voraussetzen, dass das Modell immer gültiges JSON liefert. - Multimodalität: Ob Bilder per URL oder Base64, welche Formate und Größen unterstützt werden, unterscheidet sich deutlich. Vor dem Upload Größe und Format prüfen.
- Responses API: Die neuere Schnittstelle ist bei kompatiblen Diensten weniger abgedeckt als Chat Completions; Anwendungen, die davon abhängen, müssen vor der Migration gesondert prüfen.
8. Kosten und Abrechnung
Auch die Abrechnungslogik kompatibler APIs kann abweichen:
- Klären, ob Input und Output getrennt oder gemeinsam berechnet werden.
- Klären, ob Cache-Treffer und Reasoning-Token separat berechnet werden.
- Streaming-Antworten liefern nicht unbedingt
usage; gegebenenfalls lokal Token schätzen. - Keys nach Projekt oder Geschäftsbereich trennen, damit die Monatsabstimmung möglich ist.
- Tagesbudget und Warnungen setzen, damit wiederholte Versuche die Kosten nicht aufblähen.
Konkrete Stückpreise stehen unter Modellpreise. Rechnen Sie nicht mit dem Preis eines Modells den gesamten Aufwand hoch; Modelle, Kontextlängen und Abrechnungsregeln ändern sich.
Häufige Fragen
Sind OpenAI-kompatible API und offizielle OpenAI API dasselbe?
Nein. Kompatibel bedeutet ähnliches Schnittstellenformat; Anbieter, Modelle, Abrechnung und Datenbedingungen können abweichen. Gleiche Aufrufweise bedeutet nicht gleiche Fähigkeiten oder Compliance.
Muss die Base URL /v1 enthalten?
Das hängt von der Anbieterdokumentation ab. Viele Dienste verlangen /v1, und das SDK hängt /chat/completions an; einzelne Gateways haben ein eigenes Pfadpräfix. Maßstab ist: Base URL plus /chat/completions muss den richtigen Endpunkt erreichen.
Warum funktioniert curl, das SDK meldet aber 404?
Häufig hängt das SDK den Pfad automatisch an, während die Base URL bereits /chat/completions enthält; auch eine Umgebungsvariable kann die Konfiguration im Code überschreiben. Lassen Sie die tatsächliche Request-Adresse ausgeben und vergleichen Sie.
Unterstützen kompatible Schnittstellen Tool-Aufrufe und strukturierte Ausgabe?
Teilweise, abhängig von Anbieter und Modell. Testen Sie vor der Migration eine echte Tool-Kette und ein JSON-Schema, nicht nur einen normalen Dialog.
Was tun, wenn die Antwortqualität nach der Migration sinkt?
Zuerst prüfen, ob Modellname, Temperatur und Prompt unverändert sind, dann dieselbe Stichprobe vergleichen. Bei Bedarf Prompts anpassen, Modell wechseln oder beide Anbieter parallel betreiben; urteilen Sie nicht nach ein oder zwei subjektiven Eindrücken.
Nächster Schritt
Der Wert einer OpenAI-kompatiblen API liegt in geringeren Wechselkosten – kompatibel ist aber das Protokoll, nicht die Fähigkeit. Beginnen Sie mit einem minimalen Request-Body und aktivieren Sie dann schrittweise Streaming, Tool-Aufrufe und strukturierte Ausgabe. Für einen einheitlichen OpenAI-kompatiblen Zugang, Key-Verwaltung und Verbrauchsstatistik können Sie sich für das ZSQH AI Gateway registrieren; Modelle und Preise stehen unter Modellpreise.
Weiterlesen:
