KI-APIs: Protokoll, API Key und erste Anfrage

API-Zugriff, Web-Abonnements und gemeinsam genutzte Konten

Dabei handelt es sich um unterschiedliche Produkte:

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.

Für BetterToken lauten die Base URLs:

OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

Der OpenAI-kompatible Wert enthält bereits /v1. Der Anthropic-kompatible Wert enthält es nicht; eine direkte Messages-Anfrage verwendet den vollständigen Ressourcenpfad /v1/messages.

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://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/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 BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

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 https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_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 https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_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. Wenn es speziell um Claude-kompatiblen Zugriff geht, lesen Sie zunächst die Einrichtung und Zugangsgrenzen der Claude API und kehren Sie danach zur minimalen Anfrage zurück.

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 BetterToken Workspace zeigt zum selben Zeitpunkt einen Datensatz mit Modell, Status, zutreffenden Input-/Output-/Cache-Token und Belastung.

Der Workspace ist ein Nutzungs- und Abrechnungsdatensatz. Gehen Sie nicht davon aus, dass er den vollständigen Prompt oder Antworttext speichert. Prüfen Sie Verfügbarkeit und Preise im aktuellen Modellkatalog, statt eine dynamische Liste in Ihre Integrationsnotizen zu kopieren.

7. Fehler nach Antwortschicht diagnostizieren

• 401 oder 403: Prüfen Sie Schlüssel, Key-Gruppe, Leerzeichen, Base URL und den vom gewählten Protokoll verlangten Authentifizierungs-Header.
• 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.
• 429: Lesen Sie den Antworttext, halten Sie eine angegebene Wartezeit ein und prüfen Sie aktuelle Parallelitäts- oder Ratenlimits, bevor Sie genau eine weitere Anfrage senden.
• Timeout oder TLS-Fehler: Trennen Sie lokale Proxy-, Firewall-, DNS- und Zertifikatsbedingungen von einer API-Antwort. Deaktivieren Sie die TLS-Prüfung nicht dauerhaft.
• Kein Workspace-Datensatz: Stellen Sie sicher, dass keine alte Umgebungsvariable die Anfrage zu einem anderen Anbieter geleitet hat.

Senden Sie nach einer Konfigurationsänderung erneut eine kurze Anfrage und ordnen Sie sie dem Workspace zu. Sobald das funktioniert, fügen Sie Streaming, Tools, längeren Kontext oder einen Agent-Loop schrittweise hinzu. So bleibt die Diagnosefläche jedes neuen Fehlers klein.

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.