[SYNDERESIS / API](/pl/dokumentacja/) START


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



# Buduj z Synderesis


Na tej stronie- [Buduj z Synderesis](#build-with-synderesis)- [Zacznij tutaj](#start-here)

- [Przed pierwszym żądaniem](#before-your-first-request)

- [Ustaw środowisko](#set-your-environment)

- [Wyślij pierwsze żądanie odpowiedzi](#make-your-first-answer-request)

- [Wypróbuj żądanie konwersacyjne](#try-a-conversational-request)

- [Jak kierowane są żądania](#how-requests-are-routed)

- [Sprawdź połączenie](#check-your-connection)

- [Jeśli pierwsze wywołanie się nie powiedzie](#if-the-first-call-fails)

- [Zakres dokumentacji](#documentation-scope)

- [Szybka referencja](#quick-reference)


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](/pl/dokumentacja/specyfikacja/#models-and-serving), gdy aplikacja wymaga określonego checkpointu po ponownym treningu.



## Zacznij tutaj


| Twoje zadanie | Zastosowanie |



| Zadaj pytanie z pobieraniem z oficjalnych źródeł | [Odpowiedzi](/pl/dokumentacja/specyfikacja/#post-v1answers) |

| Prowadź konwersację lub zaimplementuj wywoływanie funkcji | [Uzupełnienia czatu](/pl/dokumentacja/specyfikacja/#post-v1chatcompletions) z `synderesis-spark` |

| Znajdź fragmenty źródeł dla własnej aplikacji | [Wyszukiwanie źródeł](/pl/dokumentacja/specyfikacja/#source-search) |

| Parsuj strumieniowaną odpowiedź czatu | [Strumieniowanie i narzędzia](/pl/dokumentacja/strumieniowanie-i-narzedzia/) |

| Oszacuj użycie i zaplanuj pojemność | [Limity i rozliczenia](/pl/dokumentacja/limity-i-rozliczenia/) |

| Zmigruj istniejącą integrację | [Migracja i FAQ](/pl/dokumentacja/migracja-i-pytania/) |


**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](/pl/konto/?mode=register) i zaloguj się.

- W [Konto](/pl/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](/pl/dokumentacja/specyfikacja/#chat-dispatch-and-history) 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](/pl/dokumentacja/wdrozenie-produkcyjne/#errors-and-remedies), aby uzyskać pełną tabelę odzyskiwania. Przy integracji z aplikacją zacznij od [przykładów w językach programowania](/pl/dokumentacja/sdk-i-przyklady/).



## 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ń.


[Przegląd](/pl/dokumentacja/)[Referencja API →](/pl/dokumentacja/specyfikacja/)


[Przeczytaj ten przewodnik jako Markdown](/pl/docs/overview.md)
