Uwierzytelnianie

Każde wywołanie API, które coś tworzy, odczytuje lub rozlicza, przesyła twój klucz API w nagłówku Authorization. (Jedynym wyjątkiem jest publiczny katalog modeli do oceny oferty: nie wymaga klucza).

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Natywne API (/api/v1/*) przyjmuje wyłącznie klucze Bearer — bez plików cookie i parametrów zapytania.

Endpointy zgodności dla tekstu i wideo (/v1, /v1beta) przyjmują ten sam klucz, a dodatkowo nagłówek x-api-key używany przez SDK Anthropic i nagłówek x-goog-api-key używany przez SDK Google GenAI. Dzięki temu oficjalne SDK działają po zmianie jedynie adresu bazowego — zobacz Tekst i strumieniowanie. Te dwa nagłówki nie działają w /api/v1, a żaden endpoint nie przyjmuje klucza w parametrach zapytania URL.

Klucze API i konsola to osobne mechanizmy

Klucze API przyjmują tylko /api/v1, /v1 i /v1beta. Konsola internetowa używa własnej sesji przeglądarki. Logowania do konsoli nie można więc użyć jako klucza API, a wykradziony klucz API nie umożliwia zalogowania się do konsoli. Przesłanie niewłaściwego rodzaju danych uwierzytelniających zawsze zwraca 401, nigdy błąd uprawnień.

Jak wygląda klucz

Stały prefiks sk-spicy-, po którym następuje 48 małych znaków szesnastkowych.

Prefiks jest celowy: lepiej otrzymać powiadomienie ze skanera niż dowiedzieć się o wycieku, gdy ktoś inny zużyje twoje saldo.

Utwórz klucz

1. Otwórz Konsola → Klucze API i kliknij Utwórz klucz.
2. Nadaj mu nazwę usługi, która będzie go używać (production backend, staging worker). Przy unieważnianiu musisz móc go rozpoznać.
3. Opcjonalnie otwórz Zaawansowane, aby ustawić limity wydatków, listę dozwolonych modeli, listę dozwolonych adresów IP i datę wygaśnięcia. Wszystkie te ustawienia można później zmienić.
4. Skopiuj klucz lub kliknij Zapisz jako plik i potwierdź, że został zapisany. Po zamknięciu okna nie można go ponownie wyświetlić.

Tworzenie kluczy wymaga roli właściciela, administratora lub dewelopera w zespole. Klucz należy do zespołu wybranego w lewym górnym rogu konsoli: jego użycie i limity są liczone względem tego zespołu. Każdy zespół może mieć do 50 aktywnych kluczy. Zanim klucz będzie mógł wykonywać płatne operacje, konto musi też mieć zweryfikowany adres e-mail i środki na saldzie; zobacz Konfiguracja konta.

Gdzie przechowywać klucz

• Na swoim komputerze, do testów: export SPICY_API_KEY="…" w terminalu (działa do zamknięcia okna) albo plik .env ładowany przez twój kod. Dodaj .env do .gitignore przed pierwszym commitem.
• Na serwerze lub platformie hostingowej: użyj ustawień sekretów lub zmiennych środowiskowych i odczytuj SPICY_API_KEY ze środowiska w kodzie.
• Nigdy nie wklejaj klucza do kodu źródłowego, czatu, zrzutu ekranu, zgłoszenia do wsparcia ani promptu asystenta AI.

Nigdy nie wysyłaj klucza do klienta

To samo dotyczy plików aplikacji mobilnych, klientów desktopowych, publicznych notebooków, logów CI i wszystkiego, co trafi do wyniku curl -v wklejonego do zgłoszenia do wsparcia.

Własne narzędzia we własnej przeglądarce to inny przypadek. API przyjmuje wywołania z przeglądarek, więc narzędzia używane samodzielnie, takie jak rozszerzenie SillyTavern lub aplikacja roleplay, do których wklejasz własny klucz, mogą wywoływać je bezpośrednio. Powyższa zasada dotyczy umieszczania klucza w czymś, co wczytują inne osoby. Nadaj każdemu takiemu narzędziu osobny klucz z limitem dziennym, aby widzieć jego wydatki i móc niezależnie go unieważnić.

Ograniczenia poszczególnych kluczy

Ustaw je w konsoli podczas tworzenia klucza lub później. Są egzekwowane po stronie serwera.

Karta każdego klucza pokazuje jego aktualne limity, które możesz tam w dowolnym momencie zmienić.

Limity obejmują zarówno środki zablokowane na trwające zadania, jak i już wydane, dlatego klucz może osiągnąć limit, gdy zadania nadal są wykonywane. msg wskazuje osiągnięty limit. 40202, którego msg wspomina o limicie platformy, nie dotyczy twojego klucza: utworzenie kolejnego nie pomoże, więc spróbuj później.

Lista dozwolonych adresów IP jest sprawdzana względem twojego rzeczywistego publicznego adresu widocznego w naszej sieci brzegowej, a nie adresu ostatniego proxy. Twój adres wyjściowy to publiczny IP, z którego pochodzą żądania serwera: większość platform hostingowych podaje go w ustawieniach sieci, a na własnym komputerze sprawdzisz go przez curl https://ifconfig.me.

Zadania należą do klucza, który je utworzył

Zadanie jest widoczne przez API tylko dla klucza API, który je utworzył. Dla dowolnego innego klucza, nawet z tego samego zespołu:

Dwie rzeczy nie są związane z kluczem. Webhooki zadania są dostarczane nawet po unieważnieniu klucza, który je utworzył. Ponadto każde zadanie zespołu, niezależnie od klucza, jest widoczne w Konsola → Logi, gdzie szczegóły zadania pokazują Użyty klucz.

Rotacja

• Jeden klucz na środowisko (produkcyjne / testowe / lokalne), aby można było unieważnić jeden bez wpływu na pozostałe.
• Planowana rotacja: utwórz nowy klucz i wysyłaj nim tylko nowe zadania. Zachowaj stary klucz aktywny do chwili, gdy każde utworzone nim zadanie osiągnie stan końcowy (najpóźniej w jego deadlineAt) i odbierzesz wyniki, a następnie go unieważnij. Stosuj tę kolejność tylko wtedy, gdy stary klucz nadal jest zaufany.
• Unieważnienie działa natychmiast i nie można go cofnąć. Nie ma pamięci podręcznej, na której wygaśnięcie trzeba czekać, ani możliwości ponownego włączenia klucza; trzeba utworzyć nowy.

Po wycieku

Jeśli wystąpiły nieoczekiwane wydatki, skontaktuj się z nami przez Konsola → Wsparcie, podając identyfikatory zadań lub wartości request_id.

Jak wygląda błąd

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Status HTTP również wynosi 401. Każdy błąd uwierzytelniania zwraca code: 401, a msg określa jego rodzaj:

Logikę programu opieraj na code, nie na tekście: sformułowanie może się zmienić i zależy od języka komunikatów o błędach. Więcej o rozróżnianiu błędów w sekcji Błędy.

Gdy samo konto nie może wywoływać API (adres e-mail nie jest zweryfikowany albo konto zawieszono), zamiast tego otrzymujesz 403. Zmiana klucza nie pomoże w tym przypadku.