Uwierzytelnianie za pomocą klucza API

Brama CLEVI uwierzytelnia ścieżki zgodne z OpenAI i ścieżki zgodne z Anthropic za pomocą jednego klucza API.
W kliencie należy skonfigurować dwie wartości: nagłówek uwierzytelniania zawierający klucz oraz base URL SDK. Dozwolone formaty nagłówków i base URL różnią się w zależności od specyfikacji.
Po zakończeniu konfiguracji możesz od razu sprawdzić uwierzytelnianie, pobierając listę modeli.
Jeśli uwierzytelnianie się nie powiedzie, zwracany jest kod 401. Jeśli uwierzytelnianie powiedzie się, ale nie zostaną spełnione warunki dotyczące uprawnień lub limitów, zwracany jest kod 403.

Klucz API możesz uzyskać na ekranie kluczy API w konsoli. Na tym samym ekranie możesz zarządzać unieważnianiem kluczy i zakresem ich użycia.

Nagłówek uwierzytelniania

Obie specyfikacje umieszczają klucz API w jednym z nagłówków żądania. Możesz użyć nagłówka X-API-Key lub Authorization, a dozwolony format zależy od specyfikacji.

W ścieżce zgodnej z OpenAI podczas używania nagłówka Authorization wymagany jest prefiks Bearer. Jeśli wyślesz sam klucz bez prefiksu, brama odrzuci żądanie.

Wielkość liter w nazwie nagłówka nie ma znaczenia, dlatego nagłówek x-api-key wysyłany przez Anthropic SDK również działa bez zmian. Jeśli określisz oba nagłówki, pierwszeństwo ma wartość X-API-Key.

base URL

Istniejące SDK możesz nadal używać bez zmian, zmieniając tylko base URL na jeden z poniższych adresów. Adresy różnią się tym, czy zawierają /v1, dlatego określ dokładnie adres odpowiedni dla danej specyfikacji.

Sprawdzanie uwierzytelniania

Po ustawieniu klucza i base URL możesz sprawdzić uwierzytelnianie, pobierając listę modeli. Poniższe przykłady wykonują to samo żądanie za pomocą curl, OpenAI SDK i Anthropic SDK. W miejscu sk-... wstaw klucz wydany na ekranie kluczy API.

Podczas pobierania listy za pomocą curl w obu wariantach określ pełną ścieżkę do /v1/models. Pierwsze polecenie używa nagłówka X-API-Key dla ścieżki zgodnej z OpenAI, a drugie nagłówka Authorization dla ścieżki zgodnej z Anthropic.

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"

W OpenAI SDK ustaw adres zawierający /v1 w parametrze base_url.

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)

W Anthropic SDK ustaw base_url jako adres kończący się przed /v1.
Do uwierzytelniania używany jest bezpośrednio nagłówek x-api-key wysyłany przez SDK.

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)

Jeśli dowolny przykład zwróci odpowiedź 200, oznacza to pomyślne uwierzytelnianie, a w polu data odpowiedzi znajduje się lista modeli, które można wywoływać za pomocą tego klucza. Jeśli otrzymasz 401, sprawdź przyczynę zgodnie z kolejnością opisaną w następnej sekcji.

Nieudane uwierzytelnianie

Jeśli wyślesz nieistniejący, wygasły lub unieważniony klucz, zostanie zwrócony kod 401. W przypadku wywołania ścieżki zgodnej z OpenAI bez klucza zwracane jest poniższe ciało odpowiedzi, a w przypadku ścieżki zgodnej z Anthropic wartość error.type to authentication_error.

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

Po otrzymaniu kodu 401 sprawdź kolejno następujące elementy.

1. Sprawdź stan klucza na ekranie kluczy API. Jeśli klucz wygasł lub został unieważniony, wygeneruj nowy.
2. Sprawdź, czy nazwa nagłówka to X-API-Key lub Authorization.
3. Jeśli w ścieżce zgodnej z OpenAI używasz nagłówka Authorization, sprawdź, czy zawiera prefiks Bearer.

Po wprowadzeniu zmian ponownie wykonaj pobieranie listy modeli opisane w sekcji dotyczącej sprawdzania uwierzytelniania i sprawdź, czy otrzymasz kod 200.

Nagłówki używane wspólnie

Wszystkie poniższe nagłówki są opcjonalne. Zalecamy ustawienie X-Request-Id, aby ułatwić śledzenie problemów.

Jeśli błędy 5xx powtarzają się, poinformuj nas za pośrednictwem pomocy technicznej i kontaktu, podając X-Request-Id. Jeśli wartość została określona bezpośrednio, można ją łatwo porównać z zapisami klienta.