OpenAI-kompatible oder Anthropic-kompatible API: Was wählen?

Was API-kompatibel tatsächlich bedeutet

Eine kompatible API akzeptiert eine vertraute Anfragestruktur und liefert eine Antwort, die ein bestehendes SDK oder ein vorhandener Client verarbeiten kann. Bei einer typischen Integration ändern Entwickler Base URL, API Key und Model ID, während der größte Teil des Anwendungscodes erhalten bleibt.

Der Begriff hat eine klare Grenze. Ein Anbieter kann einfache Textgenerierung unterstützen, ohne einen bestimmten Parameter, ein gehostetes Tool, Audio, einen Bild-Endpoint oder die genaue Fehlersemantik abzudecken. Selbst zwei Endpoints mit einem Feld namens model können Modelle unterschiedlich auflisten und Zugriffsrechte anders vergeben.

Möchten Sie das gewählte Protokoll mit einer echten Anfrage testen? Sie können Ihr eigenes BetterToken-Konto und einen API Key erstellen, den Quickstart öffnen und einen minimalen Test senden. BetterToken bietet getrennte OpenAI-kompatible und Anthropic-kompatible Schnittstellen; Protokoll, Base URL, API-Key-Typ und aktuelle Model ID müssen mit der aktuellen API-Referenz übereinstimmen.

Unterschiede bei Anfragen und Authentifizierung

In einem OpenAI-kompatiblen Ablauf erstellt ein Client normalerweise messages für Chat Completions oder input für Responses. Für die Authentifizierung wird häufig ein Bearer-Token verwendet:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages verwendet eine eigene Nachrichtenstruktur, ein separates Feld system, ein verpflichtendes Ausgabelimit und eine Protokollversion. Die offizielle Anthropic API nutzt Header wie x-api-key und anthropic-version:

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Ein kompatibles Gateway kann ein anderes Authentifizierungsschema akzeptieren. Übernehmen Sie die Header aus der Dokumentation des aufgerufenen Endpoints. Ein Beispiel der offiziellen API erklärt das Protokollformat, ersetzt aber nicht die Integrationsanleitung des Anbieters.

Auch die Systemanweisung liegt in den Verträgen an unterschiedlicher Stelle. Ein Protokoll führt sie möglicherweise innerhalb der Nachrichten, ein anderes sendet sie als separates Feld. Eine mechanische Umwandlung kann die Reihenfolge des Kontexts, ein Cache-Präfix oder das Verhalten des Clients verändern.

Chat Completions, Responses und Messages sind verschiedene Verträge

Der Ausdruck OpenAI-kompatibel sagt nicht, welche Schnittstelle implementiert ist. Halten Sie vor einer Migration den genauen Vertrag fest:

• Chat Completions: ein Array messages, eine Antwort unter choices und gestreamte Fragmente unter delta.
• Responses API: Input-Items, typisierte Output-Items und getrennte Ereignisse für den Response-Lebenszyklus.
• Anthropic Messages: messages, ein separates Feld system, Content Blocks und eigene Stream-Ereignisse.

Wenn eine Bibliothek Responses erwartet, reicht ein Endpoint mit ausschließlich /chat/completions nicht aus. Wenn Claude Code Anthropic Messages erwartet, funktioniert ein OpenAI-kompatibler Endpoint nicht ohne Adapter. Nur wenn Client und Server denselben Vertrag implementieren, genügt das Ersetzen der Base URL.

Unterschiede bei Streaming und Abschluss

Alle drei Schnittstellen können Daten streamen, doch Namen und Reihenfolge ihrer Ereignisse unterscheiden sich.

Die Responses API sendet typisierte Server-Sent Events für die Erstellung der Response, Textfragmente und Endzustände. Ein Client muss auf ein Abschlussereignis warten oder eine fehlgeschlagene beziehungsweise unvollständige Antwort verarbeiten.

Anthropic Messages sendet message_start, Ereignisse für Content Blocks, message_delta und message_stop. Ein Fehler kann innerhalb eines bereits geöffneten Streams eintreffen, nachdem die anfängliche HTTP-Antwort erfolgreich war.

Bei Chat Completions sammelt der Client normalerweise choices[0].delta und erkennt das Ende nach dem Vertrag dieses Endpoints. Code, der nur auf einen Marker wartet, darf nicht ungeprüft in Responses oder Messages übernommen werden.

Ein minimaler Handler verwaltet vier Zustände:

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected ist nicht completed. Wenn die Verbindung nach einer Teilantwort endet, bewahren Sie die bereits empfangenen Ereignisse auf und entscheiden Sie, ob eine Wiederholung sicher ist.

Tool Use und strukturierte Ausgabe

Ähnliche Feldnamen wie tools und tool_calls können mehr Kompatibilität suggerieren, als tatsächlich vorhanden ist. Testen Sie mindestens:

• JSON Schema und Einschränkungen der unterstützten Typen;
• parallele Tool-Aufrufe;
• wie ein Tool-Ergebnis an das Modell zurückgesendet wird;
• die Zusammensetzung gestreamter Argumente;
• das Verhalten bei ungültigem JSON;
• strikte strukturierte Ausgabe und Schema-Ablehnungen.

Ein Adapter muss die Bedeutung eines Aufrufs erhalten und darf nicht nur Felder umbenennen. Das ist besonders bei Tools mit Seiteneffekten wichtig: Eine Wiederholung desselben Tool Calls kann eine zweite Nachricht senden, einen weiteren Datensatz anlegen oder eine Operation doppelt ausführen.

Fehler nicht allein anhand des HTTP-Status abbilden

401, 403, 404, 429 und 5xx liefern eine nützliche erste Einordnung, doch Fehlertexte und Header unterscheiden sich je nach Anbieter. Bewahren Sie Folgendes auf:

• HTTP-Status;
• Fehlertyp und Code des Anbieters;
• eine kurze Nachricht ohne Geheimnisse;
• Request ID;
• retry-bezogene Header;
• Endpoint, Protokoll und Model ID.

Protokollieren Sie weder API Key noch vollständigen Prompt oder sensible Antwort. Wenn ein Gateway Fehler normalisiert, bewahren Sie den ursprünglichen Anbieter-Code in einem sicheren internen Feld auf. Andernfalls können model not found, fehlender Zugriff und ein nicht passender Endpoint zu einem wenig hilfreichen 400 zusammenfallen.

Das richtige Protokoll auswählen

Ein fertiges KI-Tool

Lesen Sie zuerst die Dokumentation des Tools. Wenn es nach einer OpenAI Base URL fragt und Chat Completions oder Responses verwendet, wählen Sie den entsprechenden OpenAI-kompatiblen Endpoint. Wenn es ANTHROPIC_BASE_URL liest und Messages erwartet, verwenden Sie einen Anthropic-kompatiblen Endpoint.

Wählen Sie das Protokoll nicht nach dem Modellnamen. Ein Modell kann über ein Gateway verfügbar sein, während der Client weiterhin ein bestimmtes Anfrageformat verlangt.

Ihre eigene Anwendung

Die Entscheidung hängt vom bereits verwendeten SDK und den benötigten Funktionen ab. Listen Sie für eine neue Anwendung die erforderlichen Fähigkeiten auf: Streaming, Tools, strukturierte Ausgabe, Vision, Token-Nutzung, Batch-Vorgänge oder andere Endpoints. Prüfen Sie jeden Punkt in der offiziellen Dokumentation des Anbieters.

Migration zu einem anderen Anbieter

Bewerten Sie die Oberfläche des Vertrags, nicht die Zahl der geänderten Codezeilen. Ein einfacher Chat benötigt möglicherweise nur drei neue Konfigurationswerte. Eine Agent-Anwendung mit Tools, langem Verlauf, Cache und Streaming braucht normalerweise einen Adapter und Integrationstests.

Vor dem Umleiten von Produktionsverkehr testen

1. Halten Sie SDK, Endpoint und API-Version fest.
2. Kopieren Sie die exakte Model ID aus dem aktuellen Katalog.
3. Senden Sie eine kurze Anfrage ohne Tools oder Streaming.
4. Streamen Sie eine einfache Antwort bis zu ihrem Endereignis.
5. Führen Sie einen sicheren Tool Call ohne externe Seiteneffekte aus.
6. Erzeugen Sie mit einer absichtlich ungültigen Model ID einen kontrollierten Fehler.
7. Gleichen Sie usage, Status und Request ID mit dem Dashboard ab.
8. Testen Sie Timeout-Behandlung und eine begrenzte Wiederholung.

Erst danach sollten Sie echten Verkehr verlagern. Beginnen Sie bei BetterToken mit der API-Referenz, wählen Sie ein Protokoll und bestätigen Sie eine minimale Anfrage, bevor Sie Agent-Tools aktivieren.

FAQ

Bildet eine OpenAI-kompatible API die OpenAI API vollständig nach?

Nein. Der Begriff bezeichnet die Kompatibilität mit einer bestimmten Schnittstelle. Modelle, Parameter, Tools, Streaming, Fehler und zusätzliche Endpoints müssen weiterhin separat geprüft werden.

Kann ich einen Anthropic-kompatiblen Endpoint mit dem OpenAI SDK aufrufen?

Nicht direkt, wenn das SDK den OpenAI-Vertrag sendet. Verwenden Sie einen Client, der Anthropic Messages unterstützt, oder einen Adapter, der Nachrichten, Streaming und Tool Use korrekt konvertiert.

Reicht es, die Base URL zu ersetzen?

Manchmal, bei einer kurzen Textanfrage in einem bereits kompatiblen Client. Prüfen Sie bei einer Produktionsmigration trotzdem Model ID, Authentifizierung, Streaming, Tools, Fehler und Nutzung.

Welches Protokoll benötigt Claude Code?

Claude Code verwendet normalerweise eine Anthropic-kompatible Schnittstelle. Übernehmen Sie die exakten Variablen, die Base URL und die Modelleinstellungen aus der aktuellen BetterToken-Anleitung.