KI-APIs: Protokoll, API Key und erste Anfrage

Bevor Sie eine KI-API anbinden, klären Sie, welchen Vertrag Ihr Client erwartet: OpenAI-kompatibel oder Anthropic-kompatibel. Verwenden Sie anschließend die dokumentierte Base URL des Anbieters, halten Sie den API Key aus dem Quellcode heraus, senden Sie eine kurze Anfrage und prüfen Sie sowohl die Antwort als auch den Nutzungsdatensatz. Eine erfolgreich gespeicherte Einstellungsmaske beweist nicht, dass die Anfrage den vorgesehenen Endpoint erreicht hat.

Wenn Sie ein API-Gateway statt eines anbieterspezifischen Web-Abonnements benötigen, beginnen Sie mit der BetterToken-Übersicht zu KI-APIs. BetterToken stellt getrennte OpenAI-kompatible und Anthropic-kompatible Schnittstellen bereit. Sie verwenden weiterhin Ihr eigenes BetterToken-Konto und Ihren eigenen API Key; der Schlüssel ist kein Schlüssel aus der OpenAI- oder Anthropic Console.

API-Zugriff, Web-Abonnements und gemeinsam genutzte Konten

Dabei handelt es sich um unterschiedliche Produkte:

Zugangsweg	Was Sie erhalten	Was daraus nicht folgt
API-Zugriff	Mit Ihrem eigenen Schlüssel authentifizierte HTTP-Anfragen	Zugriff auf das Endnutzer-Chat-Abonnement eines Anbieters
Web-Abonnement	Eine bestimmte Produktoberfläche und die darin enthaltenen Limits	Ein übertragbares API-Guthaben oder ein API Key eines Drittanbieters
Gemeinsam genutztes Konto	Die Anmeldesitzung einer anderen Person	Eine sichere oder geeignete Produktionsintegration

Verwenden Sie für normale Entwicklungsarbeit ein Konto und einen Schlüssel, die Sie selbst kontrollieren. Bauen Sie keine Integration auf einem gekauften oder gemeinsam genutzten Login auf.

1. Protokoll anhand des Clients auswählen

Lesen Sie die Dokumentation des Clients oder SDK, bevor Sie ein Modell auswählen. Verwenden Sie OpenAI-kompatibel, wenn das Tool ein OpenAI SDK, Chat Completions, die Responses API oder ein Feld wie OPENAI_BASE_URL erwartet. Verwenden Sie Anthropic-kompatibel, wenn es Messages-Anfragen erzeugt und ANTHROPIC_BASE_URL oder x-api-key erwartet.

Der Modellname bestimmt nicht das Protokoll. Der Client muss denselben Request-Vertrag erzeugen, den der Endpoint akzeptiert.

Bei einem OpenAI-kompatiblen Anbieter können Base URL und Chat-Completions-Pfad so aussehen:

Base URL: https://api.example.com/v1
Vollständiger Pfad: https://api.example.com/v1/chat/completions

Bei einem Anthropic-kompatiblen Anbieter kann die Form so aussehen: Base URL: https://api.example.com; vollständiger Messages-Pfad: https://api.example.com/v1/messages. Das sind Formen, keine Konfigurationswerte. Kopieren Sie tatsächliche Werte nur aus der Dokumentation des gewählten Anbieters.

Müssen Sie Protokoll und Felder der ersten Anfrage prüfen? API-Konfigurationsreferenz öffnen

2. Base URL und Anfragepfad unterscheiden

Ein SDK oder Tool fragt normalerweise nach einer Base URL und hängt den Ressourcenpfad selbst an. Ein direkter HTTP-Aufruf benötigt den vollständigen Pfad.

OpenAI-compatible raw path: https://api.example.com/v1/chat/completions
Anthropic Messages raw path: https://api.example.com/v1/messages

Fügen Sie keinen vollständigen Anfragepfad in ein Feld ein, das nur eine Base URL erwartet. Andernfalls kann der Client die Ressource doppelt anhängen und einen 404-Fehler liefern.

3. API Key außerhalb des Codes speichern

Verwenden Sie für den ersten Test lokale Umgebungsvariablen und verschieben Sie Produktionszugangsdaten anschließend in den Secret Manager Ihrer Plattform.

export API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"

Schreiben Sie einen echten Schlüssel niemals in Quellcode, .env.example, einen Prompt, ein Issue, einen Screenshot oder eine Support-Nachricht. Kopieren Sie die aktuelle exakte Model ID aus der Dokumentation oder dem Modellkatalog des Anbieters, statt sie aus einem Marketingnamen abzuleiten.

4. Minimale OpenAI-kompatible Anfrage senden

Beginnen Sie mit einer kurzen reinen Textanfrage, bevor Sie Streaming oder Tools aktivieren:

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

Vermeiden Sie curl -v in Logs, die Sie mit anderen Personen teilen, da die ausführliche Ausgabe sensible Header offenlegen kann.

5. Minimale Anthropic-kompatible Anfrage senden

Die Messages-Anfrage verwendet einen anderen Authentifizierungs-Header und eine andere Body-Struktur:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSION ist ein Platzhalter. Prüfen Sie vor dem Test in der API-Referenz, welcher Header aktuell unterstützt wird.

6. Antwort und Nutzungsdatensatz prüfen

Der erste Test ist erst abgeschlossen, wenn diese Signale übereinstimmen:

Der HTTP-Status zeigt Erfolg an.
Die Antwort enthält die erwartete Model ID oder ihren dokumentierten Anzeigenamen.
Der gewählte Vertrag liefert die erwarteten Inhalts- und usage-Felder.
Der Nutzungs- oder Abrechnungsdatensatz des Anbieters zeigt die Anfrage mit erwartetem Status und Kosten.

Modellverfügbarkeit, Model IDs und Preise ändern sich. Prüfen Sie vor einer Budgetrechnung den aktuellen Katalog und die Preisseite des gewählten Anbieters.

7. Fehler nach Antwortschicht diagnostizieren

401: Prüfen Sie Schlüssel, Leerzeichen und die Authentifizierungsmethode. Bearer und x-api-key sind nicht austauschbar.
404: Vergleichen Sie die Base URL mit dem vollständigen Pfad. Suchen Sie nach einem doppelten /v1, /chat/completions oder /messages.
model not found: Kopieren Sie die aktuelle exakte Model ID und prüfen Sie, ob sie für die ausgewählte Key-Gruppe und das Protokoll verfügbar ist.
Timeout oder TLS-Fehler: Trennen Sie lokale Proxy-, Firewall-, DNS- und Zertifikatsbedingungen von einer API-Antwort. Deaktivieren Sie die TLS-Prüfung nicht dauerhaft.

Gehen Sie in dieser Reihenfolge vor: Client-Vertrag bestimmen, Schlüssel als Secret speichern, korrekte Base URL setzen, eine kurze Anfrage senden und Antwort samt Nutzungsdatensatz prüfen. Erst danach Streaming, Tools, langen Kontext oder Agent-Workflows ergänzen.

Nächster Schritt: OpenAI-kompatible API

Für einen praktischen Einrichtungsweg mit eigenem Key und OpenAI-kompatiblem Route öffnen Sie die OpenAI-API-Seite. Sie beschreibt eine kompatible BetterToken-API und keinen offiziellen OpenAI-Key.

Die Formen https://api.example.com, https://api.example.com/v1, https://api.example.com/v1/messages und https://api.example.com/v1/chat/completions sind Beispiele; verwenden Sie die dokumentierten Werte des gewählten Anbieters.