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
- Utwórz klucz zastępczy w Koncie.
- Zapisz go w odpowiednim menedżerze sekretów.
- Zaktualizuj usługę i sprawdź uwierzytelnione żądanie.
- Unieważnij poprzedni klucz w Koncie.
- 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.