SYNDERESIS / API BUILD
Hostowane API dla klientów · Kontrakt przejrzany 7 listopada 2026
Referencja API
Na tej stronie
Bazowy adres URL hostowanego API to https://www.synderesis.eu/v1. Wysyłaj JSON z Content-Type: application/json dla żądań POST i uwierzytelniaj się jednym nagłówkiem klucza API klienta.
Mapa endpointów
| Metoda i ścieżka | Cel | Uwierzytelnianie |
|---|---|---|
| GET /health | Gotowość środowiska uruchomieniowego i bazy danych; poza ścieżką bazową /v1 | Brak |
| GET /v1/models | Publiczne aliasy produktów i dostępne metadane | Klucz API |
| POST /v1/answers | Pytanie z opcjonalnym pobieraniem oficjalnych źródeł | Klucz API |
| POST /v1/chat/completions | Completion transkryptu lub adaptera odpowiedzi | Klucz API |
| GET /v1/sources/search | Wyszukiwanie fragmentów za pomocą parametrów zapytania | Klucz API |
| POST /v1/sources/search | Wyszukiwanie fragmentów z opcjonalnymi filtrami źródeł | Klucz API |
| GET /v1/usage | Podsumowanie przydziału konta, wykorzystania i środków | Klucz API |
| GET /v1/me | Przypisanie profilu i klucza | Klucz API |
Bazowy URL zawiera już /v1; dopisz /answers, a nie /v1/answers, gdy klient przyjmuje bazowy URL. Zobacz Uwierzytelnianie w sprawie cyklu życia klucza i reguł nagłówków.
Współdzielony klucz wyłącznie do inferencji (prefiks sk_inf_) może wywołać tylko POST /v1/chat/completions, POST /v1/answers i GET /v1/models. Każda inna trasa odpowiada kodem HTTP 403 inference_scope_denied. Taki klucz ma zapisaną górną granicę tokenów na cały okres życia oraz termin wygaśnięcia; zobacz Limity i rozliczenia.
Modele i serwowanie
GET /v1/models zwraca obiekt z object: "list" i tablicą data. Każdy element ma id, object: "model", owned_by: "synderesis" i provider: "synderesis".
Przejrzana implementacja wymienia:
| Identyfikator | Wskazówki integracji |
|---|---|
| spark | Usługa odpowiedzi Spark. Wyraźne żądanie używa jej bezpośrednio i nigdy nie wywołuje routera. |
| pro | Alias produktu Pro. Użyj dokładnie tego identyfikatora. |
| labora | Wymieniony alias produktu; przekazanie go do czatu nie udostępnia API orkiestracji Labora. |
| scriptor | Wymieniony alias zgodności/produktu. |
| qwen | Wymieniony alias zgodności/produktu. |
| grok | Wymieniony alias zgodności/produktu. |
| minimax | Wymieniony alias zgodności/produktu. |
| glm | Wymieniony alias zgodności/produktu. |
| synderesis-spark | Wyraźny interfejs czatu dla transkryptu i narzędzi; preferowany w przykładach SDK czatu. |
| synderesis-pro | Udokumentowany publiczny identyfikator Pro; ten sam wybór co pro. |
| synderesis-auto | Automatyczny wybór między Spark a Pro. Pominięcie model jest tym samym wyborem. |
Wpis synderesis-spark deklaruje także context_length: 65536, max_completion_tokens: 32768 i supports_tool_calls: true. Są to deklarowane metadane modelu; limity bajtów żądania, transkryptu, danych wyjściowych i konta nadal obowiązują. Program obsługi nie udostępnia punktu końcowego tokenizera do kontroli wstępnej ani nie egzekwuje tej deklarowanej liczby kontekstu jako uniwersalnej gwarancji tokenów wejściowych.
Automatyczny wybór
Dla POST /v1/answers i POST /v1/chat/completions pominięcie model jest tym samym co "model": "synderesis-auto" (alias żądania auto). Alias auto jest przyjmowany, ale nie jest własnym wierszem katalogu. Gdy routing jest włączony, jedno wywołanie routera może wybrać Spark albo Pro oraz wysiłek; tokeny routera są mierzone razem z odpowiedzią i uwzględniane w usage. Realizowana jest tylko wybrana decyzja Spark albo Pro. W przypadku wyłączonego routera, przekroczenia limitu czasu, nieprawidłowej decyzji lub decyzji o niskiej ufności albo wyboru Labora obsługiwany jest Spark przy niskim wysiłku i nigdy Pro.
Automatyczne odpowiedzi zawierają "model": "synderesis-auto" i obiekt routing: mode to spark lub pro, status to selected lub fallback, a effort to użyty wysiłek. Jawne synderesis-spark, spark, pro i synderesis-pro zachowują własne ścieżki i nigdy nie wywołują routera. Przy POST /v1/chat/completions automatyczny wybór odrzuca tools oraz wyniki narzędzi z HTTP 400 unsupported_parameter.
Aliasy są stabilnymi nazwami produktów, a nie dowodem na odrębne bazowe checkpointy lub dostawców. Implementacja obsługuje sterowaną wdrożeniem trasę z ponownie wytrenowanym checkpointem dla kwalifikujących się usług odpowiedzi i innych skonfigurowanych ścieżek serwowania. W tym API do tej trasy kwalifikuje się tylko jawne żądanie Spark lub Pro do POST /v1/answers; Chat Completions, automatyczny wybór oraz współdzielone klucze wyłącznie do inferencji nie wybierają tej trasy. Jeśli pochodzenie checkpointu, polityka fallback albo konkretny model jest wymaganiem, potwierdź ustalenia dotyczące serwowania z Synderesis przed produkcją. Same publiczne aliasy tego nie ustalają.
POST /v1/answers
Zadaj jedno pytanie. Pobieranie oficjalnych źródeł jest domyślnie włączone. Żądanie jest obiektem JSON o rozmiarze co najwyżej 65536 bajtów.
| Pole | Zalecany typ | Zachowanie |
|---|---|---|
| question | string; wymagany | Przycięte, niepuste, co najwyżej 16,000 znaków. |
| prompt | string | Starszy alias używany tylko wtedy, gdy question nie występuje. Preferuj question. |
| model | string | Pominięte, synderesis-auto lub auto wybiera automatyczny wybór. W przeciwnym razie użyj aliasu z listy; synderesis-pro to ten sam wybór co pro. |
| grounding | boolean | Domyślnie włączone; false wyłącza pobieranie oficjalnych źródeł. |
| retrieve_sources | boolean | Wcześniejsza nazwa dla grounding. Ignorowane, gdy grounding jest obecne. |
| instructions | string | Opcjonalne instrukcje stylu lub zadania. Przycięte i skrócone do 16,000 znaków; katolickie granice odpowiedzi pozostają stosowane. |
| max_tokens | integer | Domyślnie 1024. Konwertowane na liczbę całkowitą i ograniczane do 1–4096. Wyślij liczbę całkowitą z tego zakresu. |
| stream, tools | — | Ignorowane. POST /v1/answers ignoruje stream i tools; do SSE lub wywołań funkcji użyj interfejsu czatu z transkryptem. |
Implementacja zachowuje koercję liczbową dla skończonych liczb zmiennoprzecinkowych i liczbowych łańcuchów znaków w max_tokens. Wartości nieliczbowe, null, kontenery i wartości, które nie są skończone, są odrzucane. W nowej integracji nie polegaj na koercji.
Dla grounding używaj rzeczywistych wartości logicznych JSON. Wewnętrznie false, 0 i pewne łańcuchy podobne do false wyłączają grounding; pominięcie i null pozostawiają pobieranie włączone. Jeśli wysłano obie nazwy, grounding ma pierwszeństwo nawet wtedy, gdy ma wartość null. Inne nierozpoznane pola nie zyskują funkcji przez to, że zostały przyjęte.
Pobieranie używa co najwyżej pierwszych 8,000 znaków pytania i żąda co najwyżej ośmiu początkowych fragmentów. Kontekst źródłowy jest ograniczony do 16,000 znaków; fragmenty mogą zostać wybrane lub odrzucone przed generowaniem. Nie ogranicza to pełnego promptu do 16,000 znaków.
Odpowiedź answers
| Pole | Znaczenie |
|---|---|
| object | catholic_ai.answer |
| model | Publiczny alias produktu: synderesis-auto przy automatycznym wyborze, pro dla pro lub synderesis-pro, spark dla spark lub synderesis-spark. Może różnić się od żądanego aliasu. |
| customer_id | Identyfikator konta uwierzytelnionego wywołującego. |
| answer | Zwrócony tekst odpowiedzi. |
| structured_answer | null w tym natywnym handlerze. Nie oczekuj tutaj sparsowanych sekcji odpowiedzi. |
| structured_answer_validation | unvalidated_native_gateway |
| grounding_status | retrieved_sources_only; stały status w tym handlerze, w tym przy żądaniach z wyłączonym groundingiem. |
| source_refs | Tablica par source_id i location dostarczonych jako kontekst. |
| retrieved_sources | Rekordy źródłowe dostarczone do generowania. To nie jest wynik weryfikacji na poziomie zdania. |
| usage | prompt_tokens, completion_tokens, total_tokens oraz usage_event_id po zwykłym rozliczeniu. |
| retrieval_selection | Zawiera status wyboru cytowań dla zwykłej wygenerowanej odpowiedzi. |
| routing | Obecne tylko przy automatycznym wyborze: mode (spark lub pro), status (selected lub fallback) i effort. |
Pobrane rekordy zawierają source_id, location, title, url, publisher, source_type, summary i text oraz mające zastosowanie metadane źródła dotyczące autorytetu źródła i proweniencji. Tekst jest ograniczony do 2,400 znaków na zwrócony rekord. Mogą pojawić się dodatkowe metadane.
Użycie może obejmować pracę nad wyborem fragmentów i, przy automatycznym wyborze, wywołanie routera, a także generowanie odpowiedzi. Nie jest to koniecznie wyłącznie liczba tokenów pytania i odpowiedzi widocznych dla użytkownika. Użycie dostawcy jest stosowane, gdy jest prawidłowe; możliwe są ograniczone szacunki.
Dokładne pytanie o łączność Reply with exactly one word: ok ma specjalną uwierzytelnioną ścieżkę odpowiedzi. Jego wynik nie jest testem jakości modelu, pobierania ani rozliczeń. Nie zwraca usage_event_id ani retrieval_selection. Wspólny klucz wyłącznie do inferencji nie otrzymuje tego skrótu; jego sonda jest mierzona jak zwykłe żądanie. Użyj zwykłego pytania, aby przetestować rzeczywiste generowanie.
POST /v1/chat/completions
Żądanie jest obiektem JSON o wielkości co najwyżej 921600 bajtów dla chat completions. Alias modelu i pola związane z narzędziami wybierają jedną z dwóch ścieżek obsługi.
Kierowanie czatu i historia
| Żądanie | Obsługa |
|---|---|
| model to synderesis-spark | Ścieżka transkryptu/narzędzi, z narzędziami lub bez. |
| model to spark, pro lub synderesis-pro, a tools jest obecne (w tym pusta tablica) albo transkrypt zawiera rolę tool lub tool_calls | Ścieżka transkryptu/narzędzi. |
| model pominięty, auto lub synderesis-auto, z narzędziami albo historią narzędzi | 400 unsupported_parameter. |
| Dowolny inny model z narzędziami albo historią narzędzi, na przykład labora | 400 unsupported_model. |
| model pominięty, auto lub synderesis-auto, bez narzędzi ani historii narzędzi | Trafia na ścieżkę odpowiedzi z automatycznym wyborem. |
| spark, pro, synderesis-pro albo inny akceptowany alias, bez narzędzi ani historii narzędzi | Trafia na ścieżkę odpowiedzi: używa ostatniej wiadomości user i wiadomości system. |
Dla transkryptu Pro bez definicji funkcji wyślij "model":"pro","tools":[] (lub synderesis-pro). Aby zachować historię konwersacji, świadomie wybierz ścieżkę transkryptu. Adapter odpowiedzi nie wysyła wcześniejszych tur konwersacji user/assistant do generowania.
Pola żądania transkryptu/narzędzi
| Pole | Typ | Zachowanie |
|---|---|---|
| model | string | synderesis-spark albo, gdy tools jest obecne, spark, pro lub synderesis-pro. |
| messages | array; wymagane | 1–255 wiadomości z rolami system, developer, user, assistant lub tool. |
| messages[].content | string, tablica części tekstowych lub null | Części tekstowe używają type=text i pola tekstowego typu string. Akceptowane są tylko części tekstowe. null jest poprawne dla wiadomości assistant z wywołaniem narzędzia. |
| tools | array | Opcjonalne definicje funkcji; pusta tablica wybiera ścieżkę transkryptu dla obsługiwanych aliasów. |
| tool_choice | string albo obiekt nazwanej funkcji | Domyślnie auto; akceptowane są none, required albo nazwana przekazana funkcja. |
| parallel_tool_calls | boolean | Domyślnie true. |
| max_completion_tokens | integer | Ma pierwszeństwo przed max_tokens. Domyślnie 8192; prawidłowy zakres 1–32768. Jawne null używa wartości domyślnej. |
| max_tokens | integer | Używane, gdy brak max_completion_tokens; ten sam zakres i ta sama wartość domyślna. |
| stream | boolean | Domyślnie false. Wartość true zwraca buforowane SSE po wygenerowaniu. |
| stream_options | object | include_usage=true dodaje końcowy chunk usage podczas strumieniowania. |
| n | number | Obsługiwane jest tylko 1. |
| response_format | — | Na tej ścieżce musi zostać pominięte albo mieć wartość null. Tryby ustrukturyzowanego wyniku nie są tutaj obsługiwane. |
Dodatkowe pola próbkowania, seed, user, metadata i trwałości nie są przekazywane przez tę procedurę obsługi. To, że zostaną przyjęte, nie oznacza, że wpływają na zachowanie modelu. Zobacz macierz zgodności SDK.
Pełny transkrypt jest wysyłany ponownie przy każdym wywołaniu. Wszystkie oczekujące wywołania narzędzi muszą mieć odpowiadające im wyniki narzędzi przed następną zwykłą wiadomością. Zweryfikuj pełną sekwencję i postępuj zgodnie z pętlą narzędzi.
Odpowiedź transkryptu/narzędzia
Odpowiedź bez strumieniowania zawiera:
{
"id": "chatcmpl-example",
"created": 1793966400,
"object": "chat.completion",
"model": "synderesis-spark",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "Illustrative answer text."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 120, "completion_tokens": 30, "total_tokens": 150}
}
Wartości są poglądowe. Odpowiedź model jest synderesis-spark dla aliasów Spark i pro dla pro lub synderesis-pro. Wiadomość assistant może zamiast tego zawierać tool_calls oraz content dopuszczający null. Wywołanie narzędzia ma id, type=function oraz function.name i function.arguments; arguments jest ciągiem JSON, a nie zdekodowanym obiektem. Powody zakończenia mogą obejmować stop, length i tool_calls. Obsługuj nieznane przyszłe wartości bez odrzucania odpowiedzi.
Zależny od dostawcy ciąg reasoning_content roli assistant może zostać zachowany w celu kontynuacji transkryptu. Traktuj go jako opcjonalne pole transportowe; nie polegaj na jego dostępności i nie wyświetlaj ani nie loguj go domyślnie.
Różnice w żądaniach adaptera Answer
Adapter przyjmuje ostatnią wiadomość user jako pytanie i scala treść wiadomości system jako instrukcje. Wcześniejsze tury rozmowy oraz instrukcje roli developer nie są przekazywane jako pełny transkrypt. Przy automatycznym wyborze co najwyżej dwie wcześniejsze tury user (pierwsze 500 znaków każdej tury) są przekazywane wyłącznie routerowi, aby sklasyfikować pytanie uzupełniające; nie docierają do generowania odpowiedzi i nie są przechowywane.
max_tokens ma wartość domyślną 4096 i jest ograniczane do 1–4096, zgodnie z koercją endpointu answer. max_completion_tokens nie steruje tym adapterem. stream: true zwraca 400 unsupported_parameter. Adapter może używać grounding/retrieve_sources tak jak answers.
Jego odpowiedź jest mniejsza: id=chatcmpl-native, object, model, choices i usage oraz routing przy automatycznym wyborze. model jest synderesis-auto przy automatycznym wyborze, a w przeciwnym razie publicznym aliasem, na przykład spark lub pro. Odpowiedź nie zawiera created. Jego choices zawierają ciąg assistant oraz finish_reason=stop; nie używaj tej stałej wartości stop jako dowodu, że generowanie nie zostało obcięte. Pola cytowań/źródeł z odpowiedzi answer nie są zawarte w dostosowanej odpowiedzi czatu.
Wyszukiwanie źródeł
Użyj GET /v1/sources/search?query=...&limit=6 lub POST /v1/sources/search z obiektem JSON. Wymagane jest uwierzytelnienie.
| Pole | Gdzie | Zachowanie |
|---|---|---|
| query | query GET lub body POST | Niepusty ciąg wyszukiwania, co najwyżej 8,000 znaków. |
| q | query GET lub body POST | Starsze rozwiązanie zapasowe, gdy brak query. Preferuj query. |
| limit | query GET lub body POST | Liczba całkowita 1–20; domyślnie 6. |
| source_ids | body POST | Do 100 identyfikatorów, każdy o długości co najwyżej 256 znaków. Akceptowany jest również ciąg ID; preferuj tablicę. |
| source_id | body POST | Pojedyncza nazwa zgodności z pierwszeństwem przed source_ids. |
Parametr query source_ids metody GET nie jest udokumentowanym filtrem; do filtrowania użyj POST. POST stosuje zwykły limit body wynoszący 65,536 bajtów.
Odpowiedź zawiera object=source_search, query i data. Każdy wpis data zawiera source_id, location, title, url, publisher, source_type, chunk_kind, paragraph_index, summary i text. summary jest ograniczone do 1,200 znaków, a text do 4,000. Są to pobrane fragmenty; szanuj prawa ich pierwotnych wydawców.
Wyszukiwanie rezerwuje limit i przy powodzeniu rejestruje zdarzenie użycia konta z zerową liczbą tokenów generowania. Zerowa liczba tokenów generowania nie oznacza, że limity żądań są omijane. Niepowodzenia wyszukiwania zwracają obecnie service_unavailable przy kilku niepowodzeniach backendu lub limitu; nie zakładaj, że każda przyczyna limitu jest na tym punkcie końcowym ujawniana jako 429.
GET /v1/usage
Ten punkt końcowy podaje wartości dla całego konta, w tym aktywność przypisaną innym kluczom i korzystaniu z przeglądarki. Nie zwraca rejestru rozliczeń wyszczególnionego według poszczególnych żądań.
| Pole | Znaczenie |
|---|---|
| object | synderesis.usage |
| customer_id | Identyfikator konta. |
| api_key_prefix | Prefiks przedstawionego klucza; pomijany przy dostępie wyłącznie sesyjnym. |
| used_tokens | Wykorzystanie przydziału na przestrzeni okresów, w tym oczekujące zarezerwowane tokeny. |
| initial_allocation | Jednorazowy początkowy przydział tokenów należący do autoryzacji konta. |
| remaining_tokens | max(0, initial_allocation - used_tokens). |
| allocation_exhausted | Wskazuje wyczerpanie, gdy konto nie jest zwolnione przez uprawnienie płatne lub bezpłatne. |
| paid | Czy bieżące uprawnienie płatne jest uznawane. |
| complimentary | Czy bezpłatne przyznanie jest uznawane. |
| credit_used_eur | Informacyjna kwota wykorzystanych środków w euro. |
| credit_remaining_eur | Informacyjne saldo środków w euro. |
Pola tokenów nie są licznikami miesięcznego uzupełniania. Płatne konto może mieć remaining_tokens=0, podczas gdy ograniczenie bezpłatnego przydziału zostało zniesione. Pola środków są informacyjne i mogą wrócić do zera, jeśli nie można odczytać podsumowania rozliczenia; do uzgodnienia użyj Konto/wsparcie.
GET /v1/me
Uwierzytelniony klucz klienta może odczytać własny profil. Odpowiedź zawiera object=synderesis.me, customer_id, email, plan, plan_label, api_key_prefix, name, organization, chat_access, service_available i service_live.
Flagi usługi i etykiety planu są metadanymi aplikacji; nie nadają uprawnień do zarządzania kontem ani nie zastępują decyzji autoryzacyjnej rzeczywistego endpointu. Traktuj wartości profilu jako dane osobowe.
Ogólne zachowanie HTTP
Natywne odpowiedzi API zawierają nagłówki bezpieczeństwa X-Request-ID i no-store. Przy zgłaszaniu problemu użyj error.request_id i nagłówka odpowiedzi. Podane X-Request-ID jest akceptowane tylko jako 1–128 liter ASCII, cyfr, kropek, podkreśleń, dwukropków lub łączników; nieprawidłowe wartości są zastępowane.
Nieznane ścieżki zwracają 404 not_found. Nieobsługiwane metody zwracają 405 method_not_allowed, z nagłówkiem Allow, gdy ma to zastosowanie. OPTIONS jest uwzględniane, ponieważ API klienta nie włącza CORS.
W tym środowisku uruchomieniowym nie ma ogólnie publikowanego przez serwer /openapi.json ani Swagger UI. Ta referencja i odpowiadająca jej implementacja w repozytorium definiują sprawdzoną powierzchnię.