Mit API-Schlüssel authentifizieren

Das CLEVI-Gateway authentifiziert den OpenAI-kompatiblen Pfad und den Anthropic-kompatiblen Pfad mit einem einzigen API-Schlüssel.
Auf Client-Seite müssen zwei Werte konfiguriert werden: der Authentifizierungs-Header mit dem Schlüssel und die base URL der SDK. Das zulässige Header-Format und die base URL unterscheiden sich je nach Spezifikation.
Nach Abschluss der Konfiguration können Sie die Authentifizierung sofort überprüfen, indem Sie die Modellliste abrufen.
Bei fehlgeschlagener Authentifizierung wird 401 zurückgegeben. Wenn nach erfolgreicher Authentifizierung die Berechtigungs- oder Kontingentbedingungen nicht erfüllt sind, wird 403 zurückgegeben.

Stellen Sie den API-Schlüssel im API-Schlüssel-Bereich der Konsole aus. Im selben Bereich können Sie den Schlüssel widerrufen und seinen Nutzungsumfang verwalten.

Authentifizierungs-Header

Beide Spezifikationen übertragen den API-Schlüssel in einem Request-Header. Verwenden Sie entweder den X-API-Key-Header oder den Authorization-Header. Das zulässige Format unterscheidet sich je nach Spezifikation.

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 der 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 den bisher 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 API-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. Setzen Sie anstelle von sk-... den auf der API-Schlüsselseite ausgestellten Schlüssel ein.

Beim Abrufen mit curl geben Sie für beide Spezifikationen den vollständigen Pfad bis /v1/models an. Der erste Befehl verwendet den X-API-Key-Header für den OpenAI-kompatiblen Pfad, der zweite Befehl den Authorization-Header 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"

Beim OpenAI SDK geben Sie bei base_url eine Adresse an, die /v1 enthält.

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)

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

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 Antworttext 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 Folgendes in dieser Reihenfolge.

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

Führen Sie nach der Korrektur die Abfrage der Modellliste im Abschnitt zur Authentifizierungsprüfung erneut aus und überprü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 wiederholt 5xx-Fehler auftreten, informieren Sie uns bitte über die Hilfe und den Support – zusammen mit der X-Request-Id. Bei direkt angegebenen Werten können Sie diese unmittelbar mit den Client-Protokollen abgleichen.