Przejdź do dokumentacji

SYNDERESIS / API START

Hostowane API dla klientów · Kontrakt przejrzany 7 listopada 2026

Uwierzytelnianie i klucze API

Na tej stronie

Używaj klucza API klienta ze swojego backendu. To samo konto jest właścicielem swoich kluczy, alokacji, uprawnienia i użycia.

Wyślij dokładnie jeden nagłówek poświadczeń

Preferowane:

Authorization: Bearer <key>
Content-Type: application/json

Alternatywa:

X-API-Key: <key>
Content-Type: application/json

Przykłady pokazują składnię nagłówka; zastąp klucz za pomocą menedżera sekretów lub zmiennej środowiskowej. Nigdy nie wysyłaj obu nagłówków klucza. Wartość Authorization musi używać dokładnie pokazanego schematu Bearer. Nie umieszczaj klucza w ciągu zapytania, publicznym repozytorium, JavaScript przeglądarki, pakiecie mobilnym ani w konfiguracji do pobrania.

Nazwy nagłówków nie rozróżniają wielkości liter. Wartości poświadczeń są sekretami i muszą zostać zachowane dokładnie. Błędy kopiowania na początku lub na końcu albo obcięty klucz mogą spowodować 401.

Utwórz i zapisz klucz

Zaloguj się na Konto i utwórz klucz API klienta. Zapisz kompletny klucz, gdy jest wyświetlany; późniejsze listy kluczy zawierają jego prefiks i metadane, a nie pełną wartość.

Konto może mieć do 10 aktywnych kluczy klienta/rozszerzenia. Zarządzane przez serwer klucze pomiaru przeglądarki nie zajmują miejsca klienta ani nie pojawiają się na liście kluczy klienta. Nowy klucz współdzieli istniejącą autoryzację konta i jego przydział.

Rejestracja nie wystawia automatycznie klucza klienta. Sesja witryny i klucz API to różne poświadczenia.

Współdzielone klucze wyłącznie do inferencji

Współdzielony klucz wyłącznie do inferencji zaczyna się od sk_inf_. Jest wydawany przez operatora dla odrębnej, dedykowanej tożsamości tego klucza; nie jest tworzony w Koncie i nie jest jednym z kluczy klienta Twojego konta. Może wywoływać tylko POST /v1/chat/completions, POST /v1/answers i GET /v1/models; każda inna trasa odpowiada kodem HTTP 403 inference_scope_denied. Jego zapisany limit tokenów na cały okres życia oraz wygaśnięcie są opisane pod nagłówkiem Limity i rozliczenia. Żądanie w chwili jego wygaśnięcia lub później jest odrzucane z kodem HTTP 401 unauthorized.

Oddzielne środowiska

Utwórz oddzielne klucze dla środowiska deweloperskiego, staging i produkcji, o ile pozwala na to limit kluczy konta. Przechowuj każdy klucz tylko we wdrożeniu, które go potrzebuje. Monitoruj według prefiksu klucza i nie umieszczaj pełnej wartości w logach, trace'ach, raportach o awariach ani zgłoszeniach do wsparcia.

Oddzielne klucze nadal współdzielą limity konta. Użyj oddzielnie aprowizowanych kont lub osobno uzgodnionego porozumienia o usłudze, jeśli potrzebujesz silniejszej izolacji organizacyjnej lub niezależnie zarządzanych kwot.

Rotuj klucz

  1. Utwórz klucz zastępczy w Koncie.
  2. Zapisz go w odpowiednim menedżerze sekretów.
  3. Zaktualizuj usługę i sprawdź uwierzytelnione żądanie.
  4. Unieważnij poprzedni klucz w Koncie.
  5. Potwierdź, że pozostałe usługi się przełączyły.

Rotacja to ten przebieg zastępowania i unieważniania; sprawdzone API klienta nie udostępnia dedykowanego endpointu rotacji ani udokumentowanej obietnicy okresu karencji.

Jeśli klucz mógł wyciec, unieważnij go i zastąp go. Sprawdź nieoczekiwane użycie i usuń ujawnioną wartość z dotkniętej konfiguracji. Nie wysyłaj starego ani nowego klucza do wsparcia.

Granica API zarządzania kluczami

Witryna używa GET/POST /v1/account/keys oraz DELETE /v1/account/keys/{prefix} do zarządzania kluczami. Są to sesyjnie autoryzowane mechanizmy sterowania kontem. Klucz API klienta nie wystarcza, aby administrować innymi kluczami ani je wystawiać.

Mutacje w sesji przeglądarki również wymagają zabezpieczeń CSRF usługi. Użyj Konta do normalnego przebiegu zarządzania kluczami; nie przenoś plików cookie przeglądarki do serwerowego SDK.

Błędy uwierzytelniania

Objaw Działanie
Brak klucza API Sprawdź środowisko w rzeczywistym procesie serwera i wyślij jeden nagłówek z danymi uwierzytelniającymi.
Nieprawidłowy klucz API Sprawdź kopiowanie, unieważnienie/wygaśnięcie i konto; w razie potrzeby utwórz zamiennik.
Przekazano oba nagłówki Usuń jeden z nich. Nie polegaj na pierwszeństwie nagłówków.
Schemat Authorization odrzucony Użyj Authorization: Bearer, a następnie klucza, albo użyj X-API-Key.
Cookie działa w witrynie, ale SDK zawodzi Podaj klucz API klienta; ścieżka czatu transkryptu/narzędzia nie akceptuje samej sesji.
Błąd Origin lub CSRF Utrzymuj wywołania serwera wolne od plików cookie sesji przeglądarki; do sterowania w przeglądarce używaj obsługiwanego interfejsu konta.
403 inference_scope_denied Współdzielony klucz przeznaczony wyłącznie do inferencji wywołał trasę poza swoim zakresem. Używaj go tylko do odpowiedzi, uzupełnień czatu i wykrywania modeli.

Żądanie może nie przejść walidacji modelu lub body przed uwierzytelnieniem. Odpowiedź unsupported_model nie dowodzi, że przekazany klucz jest prawidłowy.

Zobacz wskazówki dla środowiska produkcyjnego dotyczące identyfikatorów żądań, ponownych prób i rejestrowania operacyjnego.

Przeczytaj ten przewodnik jako Markdown