Authentifizierung mit API-Schlüssel

Das CLEVI-Gateway authentifiziert sowohl OpenAI-kompatible Pfade als auch Anthropic-kompatible Pfade mit einem einzigen API-Schlüssel.
Im Client müssen zwei Werte festgelegt werden: der Authentifizierungs-Header mit dem Schlüssel und die base URL des SDKs. Das zulässige Header-Format und die base URL unterscheiden sich je nach Spezifikation.
Nach Abschluss der Konfiguration können Sie durch Abrufen der Modellliste sofort überprüfen, ob die Authentifizierung erfolgreich war.
Bei fehlgeschlagener Authentifizierung wird 401 zurückgegeben. Wenn die Authentifizierung erfolgreich war, aber Berechtigungs- oder Kontingentbedingungen nicht erfüllt sind, wird 403 zurückgegeben.

Stellen Sie den API-Schlüssel auf der API-Schlüsselseite der Konsole aus. Auf derselben Seite können Sie den Schlüssel widerrufen und seinen Nutzungsumfang verwalten.

Authentifizierungs-Header

Beide Spezifikationen übertragen den API-Schlüssel in einem Anfrage-Header. Verwenden Sie entweder den X-API-Key-Header oder den Authorization-Header. Das zulässige Format hängt von der jeweiligen Spezifikation ab.

Bei Verwendung des Authorization-Headers im OpenAI-kompatiblen Pfad ist das Präfix Bearer erforderlich. Wenn nur der Schlüssel ohne Präfix gesendet wird, lehnt das Gateway die Anfrage ab.

Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden, daher funktioniert auch der von Anthropic SDK gesendete x-api-key-Header unverändert. Wenn beide Header angegeben werden, hat der Wert von X-API-Key Vorrang.

base URL

Bei bereits verwendeten SDKs müssen Sie lediglich die base URL in die unten angegebene Adresse ändern, um sie unverändert weiterzuverwenden. Die beiden Adressen unterscheiden sich darin, ob sie /v1 enthalten. Geben Sie daher die zur jeweiligen Spezifikation passende Adresse unverändert an.

Authentifizierung überprüfen

Nachdem Sie den Schlüssel und die base URL festgelegt haben, können Sie durch Abrufen der Modellliste überprüfen, ob die Authentifizierung funktioniert. Die folgenden Beispiele führen dieselbe Abfrage mit curl, dem OpenAI SDK und dem Anthropic SDK aus. Ersetzen Sie sk-... durch den im API-Schlüsselbereich ausgestellten Schlüssel.

Beim Abrufen mit curl geben Sie für beide Spezifikationen den vollständigen Pfad bis einschließlich /v1/models an. Der erste Befehl verwendet den Header X-API-Key für den OpenAI-kompatiblen Pfad, der zweite den Header Authorization für den Anthropic-kompatiblen Pfad.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

Geben Sie beim OpenAI SDK eine Adresse einschließlich /v1 in base_url an.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

Geben Sie beim Anthropic SDK eine Adresse für base_url an, die vor /v1 endet.
Verwenden Sie für die Authentifizierung unverändert den vom SDK gesendeten Header x-api-key.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

Wenn die Antwort bei einem der Beispiele 200 lautet, war die Authentifizierung erfolgreich. In data der Antwort ist die Liste der Modelle enthalten, die mit diesem Schlüssel aufgerufen werden können. Bei 401 prüfen Sie die Ursache in der Reihenfolge des nächsten Abschnitts.

Authentifizierungsfehler

Wenn Sie keinen Schlüssel oder einen abgelaufenen bzw. widerrufenen Schlüssel senden, wird 401 zurückgegeben. Wenn Sie den OpenAI-kompatiblen Pfad ohne Schlüssel aufrufen, wird der folgende Text zurückgegeben; beim Anthropic-kompatiblen Pfad lautet error.type authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

Wenn Sie 401 erhalten, prüfen Sie dies in der folgenden Reihenfolge.

1. Prüfen Sie den Schlüsselstatus im API-Schlüsselbereich. Stellen Sie einen neuen Schlüssel aus, wenn der Schlüssel abgelaufen oder widerrufen ist.
2. Prüfen Sie, ob der Header X-API-Key oder Authorization heißt.
3. Wenn Sie im OpenAI-kompatiblen Pfad den Header Authorization verwenden, prüfen Sie, ob das Präfix Bearer vorhanden ist.

Führen Sie nach der Korrektur die Abfrage der Modellliste im Abschnitt zur Überprüfung der Authentifizierung erneut aus und prüfen Sie, ob 200 zurückgegeben wird.

Gemeinsam verwendete Header

Alle folgenden Header sind optional. Damit Probleme nachverfolgt werden können, empfehlen wir, X-Request-Id festzulegen.

Wenn 5xx-Fehler wiederholt auftreten, teilen Sie uns dies bitte zusammen mit X-Request-Id über die Hilfe und den Kontakt mit. Wenn der Wert direkt angegeben wurde, kann er unmittelbar mit den Client-Protokollen abgeglichen werden.