Przejdź do dokumentacji

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

  1. Utwórz konto i zaloguj się.
  2. W Konto otwórz sekcję kluczy API i utwórz klucz klienta.
  3. Skopiuj klucz od razu. Jego pełna wartość jest pokazywana tylko raz.
  4. Umieść go w menedżerze sekretów swojego serwera albo w lokalnej zmiennej środowiskowej.
  5. 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ń tools z żądania z automatycznym wyborem lub stream z żą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ń.

Przeczytaj ten przewodnik jako Markdown