SYNDERESIS / API START
Hostowane API dla klientów · Kontrakt sprawdzony 7 listopada 2026
Buduj z Synderesis
Na tej stronie
Synderesis to model o otwartych wagach, poddany ponownemu treningowi, aby był zgodny z wartościami katolickimi. Wprowadzaj jasny katolicki cel do aplikacji, które tworzysz, z wyraźnym kontraktem API i kontrolą nad tym, jak integrujesz.
Ten przewodnik obejmuje hostowane API dla klientów: odpowiedzi, uzupełnienia czatu, wyszukiwanie źródeł, odkrywanie modeli, użycie i odczyty profilu. Aliasy produktów identyfikują usługę API; ich konfiguracja serwowania może się różnić. Zobacz Modele i serwowanie, gdy aplikacja wymaga określonego checkpointu po ponownym treningu.
Zacznij tutaj
| Twoje zadanie | Zastosowanie |
|---|---|
| Zadaj pytanie z pobieraniem z oficjalnych źródeł | Odpowiedzi |
| Prowadź konwersację lub zaimplementuj wywoływanie funkcji | Uzupełnienia czatu z synderesis-spark |
| Znajdź fragmenty źródeł dla własnej aplikacji | Wyszukiwanie źródeł |
| Parsuj strumieniowaną odpowiedź czatu | Strumieniowanie i narzędzia |
| Oszacuj użycie i zaplanuj pojemność | Limity i rozliczenia |
| Zmigruj istniejącą integrację | Migracja i FAQ |
Bazowy adres URL API: https://www.synderesis.eu/v1
Żądania i odpowiedzi używają JSON, chyba że udokumentowane żądanie czatu włącza Server-Sent Events. Używaj HTTPS ze swojego backendu. Przechowuj tam klucz API. Żądania cross-origin z przeglądarki nie są włączone.
Przed pierwszym żądaniem
- Utwórz konto i zaloguj się.
- W Konto otwórz sekcję kluczy API i utwórz klucz klienta.
- Skopiuj klucz od razu. Jego pełna wartość jest pokazywana tylko raz.
- Umieść go w menedżerze sekretów swojego serwera albo w lokalnej zmiennej środowiskowej.
- Sprawdź bezpłatny przydział lub subskrypcję i środki swojego konta, zanim wyślesz ruch produkcyjny.
Wszystkie klucze na koncie współdzielą przydział i użycie. Osobny klucz daje atrybucję i kontrolę unieważniania; nie tworzy dodatkowego limitu.
Ustaw środowisko
Te przykłady używają SYNDERESIS_API_KEY jako konwencji zmiennej środowiskowej po stronie klienta. Nie jest to parametr żądania.
macOS lub Linux:
printf "Synderesis API key: "
read -rs SYNDERESIS_API_KEY
export SYNDERESIS_API_KEY
printf '\n'
PowerShell 7:
$env:SYNDERESIS_API_KEY = Read-Host -MaskInput "Synderesis API key"
Na potrzeby automatyzacji wstrzyknij zmienną przez menedżer sekretów swojego wdrożenia. Unikaj wpisywania prawdziwego klucza bezpośrednio w polecenia, które trafiają do historii powłoki.
Wyślij pierwsze żądanie odpowiedzi
curl --fail-with-body https://www.synderesis.eu/v1/answers \
-H "Authorization: Bearer $SYNDERESIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"model":"spark","question":"Explain human dignity in two sentences.","grounding":true,"max_tokens":1024}'
Odczytaj pole answer. Punkt końcowy zwraca obok niego metadane źródeł i użycia. Wygenerowany tekst i pobrane fragmenty różnią się między żądaniami.
Minimalny wynik schematyczny to:
{
"object": "catholic_ai.answer",
"model": "spark",
"customer_id": "example-account",
"answer": "Illustrative answer text.",
"structured_answer": null,
"structured_answer_validation": "unvalidated_native_gateway",
"grounding_status": "retrieved_sources_only",
"source_refs": [],
"retrieved_sources": [],
"usage": {
"prompt_tokens": 120,
"completion_tokens": 30,
"total_tokens": 150,
"usage_event_id": 123
},
"retrieval_selection": {"status": "off"}
}
To ilustracja schematu, a nie przechwycona generacja produkcyjna. Materiał referencyjny wyjaśnia, które pola się zmieniają. Pobrane źródła są materiałem pomocniczym, a nie gwarancją, że każde zdanie jest zweryfikowane względem nich.
Wypróbuj żądanie konwersacyjne
Użyj jawnego aliasu synderesis-spark dla interfejsu czatu, który zachowuje transkrypt:
curl --fail-with-body https://www.synderesis.eu/v1/chat/completions \
-H "Authorization: Bearer $SYNDERESIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"model":"synderesis-spark","messages":[{"role":"user","content":"Explain human dignity in two sentences."}],"max_completion_tokens":1024}'
Odczytaj choices[0].message.content. Aby kontynuować, wyślij ponownie istotne wiadomości konwersacji; ten punkt końcowy nie tworzy konwersacji zapisanej na serwerze.
Aliasy spark i synderesis-spark wybierają różne ścieżki obsługi czatu. Sprawdź tabelę aliasów przed migracją.
Jak przebiega routing żądań
Pominięcie model albo wysłanie synderesis-auto lub auto wybiera automatyczny routing na POST /v1/answers i POST /v1/chat/completions. model odpowiedzi to synderesis-auto, z obiektem routing: mode to spark lub pro, status to selected lub fallback, a effort to użyty wysiłek. Realizowana jest tylko wybrana decyzja Spark lub Pro. Jeśli routing jest wyłączony, przekroczy limit czasu albo zwróci cokolwiek innego, w tym wybór Labora, żądanie jest obsługiwane jako Spark przy niskim wysiłku. Tokeny routera są zawarte w usage, gdy wykonywane jest wywołanie routera. Jawne synderesis-spark, spark, synderesis-pro i pro zachowują własne trasy i nie wywołują routera; synderesis-pro to ten sam wybór co pro.
POST /v1/answers przyjmuje question o długości co najwyżej 16000 znaków. max_tokens ma wartość domyślną 1024 i podlega ograniczeniu do 1–4096. Limit treści żądania wynosi 65536 bajtów. structured_answer jest null, a pobrane fragmenty to source_refs i retrieved_sources. POST /v1/answers ignoruje stream i tools.
POST /v1/chat/completions ma limit treści 921600 bajtów. Żądanie trafia na ścieżkę narzędzi, gdy model jest synderesis-spark, z narzędziami lub bez, albo gdy model jest spark, pro lub synderesis-pro i żądanie zawiera tools albo transkrypt narzędzia. Każde inne uzupełnienie czatu, w tym automatyczny wybór, trafia na ścieżkę odpowiedzi. Na ścieżce odpowiedzi pominięcie max_tokens używa 4096, wartości są ograniczane do 1–4096, a stream ustawione na true jest HTTP 400 unsupported_parameter. Automatyczny wybór odrzuca tools i wyniki narzędzi z HTTP 400 unsupported_parameter. Każdy inny identyfikator modelu wysłany z narzędziami, na przykład labora, jest HTTP 400 unsupported_model.
Na ścieżce narzędzi stream: true zwraca gotową odpowiedź jako Server-Sent Events po walidacji i zarejestrowaniu użycia. Jest to buforowane dostarczanie, a nie strumieniowanie tokenów na żywo. Ścieżka narzędzi dopuszcza do 128 definicji funkcji, 255 wiadomości i 1–32768 tokenów uzupełnienia (8192, jeśli nie wysłano ani max_completion_tokens, ani max_tokens). Limit uzupełnienia spoza tego zakresu to HTTP 400 invalid_request.
Sprawdź połączenie
curl --fail-with-body https://www.synderesis.eu/v1/models \
-H "Authorization: Bearer $SYNDERESIS_API_KEY"
Wykrywanie modeli wymaga uwierzytelnienia. Do sprawdzenia gotowości bez poświadczeń użyj GET https://www.synderesis.eu/health. Zdrowa odpowiedź to {"status":"ok","service":"synderesis-api"}; nie dowodzi to, że Twoje konto może wygenerować odpowiedź.
Jeśli pierwsze wywołanie się nie powiedzie
Odpowiedź 401 oznacza, że uwierzytelnienie nie powiodło się. Sprawdź, czy zmienna jest dostępna dla procesu i czy wysyłasz dokładnie jeden nagłówek klucza. Odpowiedź 400 może wskazywać na problem z żądaniem lub modelem. Odpowiedź 402 może wskazywać wyczerpany bezpłatny przydział lub niewystarczające środki na koncie. Odpowiedź 429 dotycząca limitu wymaga środka zaradczego po stronie konta lub planu.
Zobacz Błędy i ponowienia, aby uzyskać pełną tabelę odzyskiwania. Przy integracji z aplikacją zacznij od przykładów w językach programowania.
Zakres dokumentacji
Referencja opisuje natywną hostowaną implementację przejrzaną w dniu 6 listopada 2026 i zaktualizowaną względem źródła w dniu 7 listopada 2026. Uwierzytelnione kontrole produkcyjne potwierdziły wykrywanie modeli, użycie konta, odpowiedzi, czat, buforowane SSE, propozycje funkcji i ich kontynuację, czat transkryptu Pro oraz wyszukiwanie źródeł na zgodnym wdrożonym buildzie. Wybrane metody SDK sprawdzono dodatkowo względem rzeczywistych handlerów z syntetycznymi zależnościami. Kontrole te weryfikują wykonany kontrakt integracji, a nie ogólną gwarancję jakości modelu ani przepustowości. Automatyczny wybór, identyfikator synderesis-pro oraz współdzielone klucze wyłącznie do inferencji dodano później 6 listopada 2026, po tych kontrolach; ich opis tutaj przejrzano względem kodu źródłowego, a nie potwierdzono go wywołaniem na żywo.
Powierzchnie konta/sesji, obszaru roboczego przeglądarki, urządzenia, desktopu, Code i MCP mają osobne kontrakty uwierzytelniania i aplikacji. Nie są one automatycznie wymienne z udokumentowanymi tutaj punktami końcowymi dla klientów.
Skrócona referencja
Limit treści odpowiedzi wynosi 65536 bajtów; limit wynosi 921600 bajtów dla uzupełnień czatu. Użyj z referencji dokładnie tego punktu końcowego, tej metody i tego selektora modelu.
400 unsupported_parameter: przy uzupełnieniach czatu usuńtoolsz żądania z automatycznym wyborem lubstreamz żądania na ścieżce odpowiedzi.404 not_found: sprawdź ścieżkę.405 method_not_allowed: sprawdź metodę HTTP; żądania OPTIONS przeglądarki nie są obsługiwane.401 unauthorized: sprawdź klucz klienta i wyślij dokładnie jeden nagłówek poświadczeń.