Zur Dokumentation springen

SYNDERESIS / API START

Gehostete Kunden-API · Vertrag geprüft am 7. November 2026

Mit Synderesis entwickeln

Auf dieser Seite

Synderesis ist ein Modell mit offenen Gewichten, das nachtrainiert wurde, um sich an katholischen Werten auszurichten. Bringen Sie einen klaren katholischen Zweck in die Anwendungen, die Sie entwickeln, mit einem expliziten API-Vertrag und Kontrolle darüber, wie Sie integrieren.

Dieser Leitfaden umfasst die gehostete Kunden-API: Antworten, Chat-Completions, Quellensuche, Modellermittlung, Nutzung und Profilabrufe. Produkt-Aliase identifizieren einen API-Dienst; ihre Serving-Konfiguration kann variieren. Siehe Modelle und Serving, wenn Ihre Anwendung einen bestimmten nachtrainierten Checkpoint erfordert.

Hier beginnen

Ihre Aufgabe Verwendung
Stellen Sie eine Frage mit Abruf aus offiziellen Quellen Antworten
Führen Sie eine Konversation oder implementieren Sie Funktionsaufrufe Chat-Completions mit synderesis-spark
Quellenpassagen für Ihre eigene Anwendung finden Quellensuche
Eine gestreamte Chat-Antwort parsen Streaming und Tools
Nutzung schätzen und Kapazität planen Limits und Abrechnung
Eine bestehende Integration migrieren Migration und FAQs

API-Basis-URL: https://www.synderesis.eu/v1

Anfragen und Antworten verwenden JSON, es sei denn, eine dokumentierte Chat-Anfrage aktiviert Server-Sent Events. Verwenden Sie HTTPS von Ihrem Backend aus. Bewahren Sie den API-Schlüssel dort auf. Cross-Origin-Anfragen aus dem Browser sind nicht aktiviert.

Vor Ihrer ersten Anfrage

  1. Erstellen Sie ein Konto und melden Sie sich an.
  2. Öffnen Sie in Konto den Bereich API-Schlüssel und erstellen Sie einen Kundenschlüssel.
  3. Kopieren Sie den Schlüssel sofort. Sein vollständiger Wert wird nur einmal angezeigt.
  4. Hinterlegen Sie ihn im Secret Manager Ihres Servers oder in einer lokalen Umgebungsvariablen.
  5. Prüfen Sie das kostenlose Kontingent oder das Abonnement und das Guthaben Ihres Kontos, bevor Sie Produktivverkehr senden.

Alle Schlüssel auf dem Konto teilen sich Kontingent und Nutzung. Ein separater Schlüssel ermöglicht Zuordnung und Widerrufskontrolle; er erzeugt keine zusätzliche Quote.

Ihre Umgebung festlegen

Diese Beispiele verwenden SYNDERESIS_API_KEY als clientseitige Konvention für eine Umgebungsvariable. Es ist kein Anfrageparameter.

macOS oder 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"

Injizieren Sie die Variable für die Automatisierung über den Secret Manager Ihrer Bereitstellung. Vermeiden Sie es, einen echten Schlüssel direkt in Befehle einzugeben, die in den Shell-Verlauf eingehen.

Ihre erste Antwortanfrage stellen

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}'

Lesen Sie das Feld answer. Der Endpunkt gibt neben ihm Quellen- und Nutzungsmetadaten zurück. Generierter Text und abgerufene Passagen variieren zwischen den Anfragen.

Ein minimales schematisches Ergebnis ist:

{
  "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"}
}

Dies ist eine Schemaveranschaulichung, keine erfasste Produktivgenerierung. Die Referenz erläutert, welche Felder variieren. Abgerufene Quellen sind unterstützendes Material, keine Garantie dafür, dass jeder Satz gegen sie validiert ist.

Eine Konversationsanfrage ausprobieren

Verwenden Sie den expliziten Alias synderesis-spark für die Chat-Schnittstelle, die das Transkript bewahrt:

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}'

Lesen Sie choices[0].message.content. Um fortzufahren, senden Sie die relevanten Konversationsnachrichten erneut; dieser Endpunkt erstellt keine auf dem Server gespeicherte Konversation.

Die Aliase spark und synderesis-spark wählen unterschiedliche Verarbeitungspfade für den Chat. Prüfen Sie die Alias-Tabelle, bevor Sie migrieren.

Wie Anfragen geroutet werden

Das Weglassen von model oder das Senden von synderesis-auto oder auto wählt automatisches Routing auf POST /v1/answers und POST /v1/chat/completions. Das model der Antwort ist synderesis-auto, mit einem routing-Objekt: mode ist spark oder pro, status ist selected oder fallback, und effort ist der verwendete Aufwand. Befolgt wird nur eine ausgewählte Spark- oder Pro-Entscheidung. Wenn das Routing aus ist, in eine Zeitüberschreitung läuft oder etwas anderes zurückgibt, einschließlich einer Labora-Auswahl, wird die Anfrage als Spark mit geringem Aufwand bedient. Router-Token sind in usage enthalten, wenn ein Router-Aufruf ausgeführt wird. Explizite synderesis-spark, spark, synderesis-pro und pro behalten ihre eigenen Routen und rufen den Router nicht auf; synderesis-pro ist dieselbe Auswahl wie pro.

POST /v1/answers akzeptiert ein question von höchstens 16000 Zeichen. max_tokens hat den Standardwert 1024 und wird auf 1–4096 begrenzt. Das Limit für den Request-Body beträgt 65536 Bytes. structured_answer ist null, und abgerufene Passagen sind source_refs und retrieved_sources. POST /v1/answers ignoriert stream und tools.

POST /v1/chat/completions hat ein Body-Limit von 921600 Bytes. Eine Anfrage nimmt den Tool-Pfad, wenn model synderesis-spark ist, mit oder ohne Tools, oder wenn model spark, pro oder synderesis-pro ist und die Anfrage tools oder ein Tool-Transkript enthält. Jede andere Chat-Completion, einschließlich automatischer Auswahl, nimmt den Antwort-Pfad. Auf dem Antwort-Pfad wird beim Weglassen von max_tokens 4096 verwendet, Werte werden auf 1–4096 begrenzt, und stream gesetzt auf true ist HTTP 400 unsupported_parameter. Die automatische Auswahl lehnt tools und Tool-Ergebnisse mit HTTP 400 unsupported_parameter ab. Jede andere Modell-ID, die mit Tools gesendet wird, zum Beispiel labora, ist HTTP 400 unsupported_model.

Auf dem Tool-Pfad gibt stream: true die fertige Antwort nach der Validierung und der Nutzungserfassung als Server-Sent Events zurück. Das ist eine gepufferte Auslieferung, kein Live-Token-Streaming. Der Tool-Pfad erlaubt bis zu 128 Funktionsdefinitionen, 255 Nachrichten und 1–32768 Completion-Token (8192, wenn weder max_completion_tokens noch max_tokens gesendet wird). Ein Completion-Limit außerhalb dieses Bereichs ist HTTP 400 invalid_request.

Prüfen Sie Ihre Verbindung

curl --fail-with-body https://www.synderesis.eu/v1/models \
  -H "Authorization: Bearer $SYNDERESIS_API_KEY"

Die Modellerkennung erfordert eine Authentifizierung. Für eine Bereitschaftsprüfung ohne Anmeldedaten verwenden Sie GET https://www.synderesis.eu/health. Eine gesunde Antwort ist {"status":"ok","service":"synderesis-api"}; dies beweist nicht, dass Ihr Konto eine Antwort erzeugen kann.

Wenn der erste Aufruf fehlschlägt

Eine 401-Antwort bedeutet, dass die Authentifizierung fehlgeschlagen ist. Prüfen Sie, ob die Variable für den Prozess verfügbar ist und ob Sie genau einen Schlüssel-Header senden. Eine 400-Antwort kann auf ein Anfrage- oder Modellproblem hinweisen. Eine 402-Antwort kann eine aufgebrauchte kostenlose Zuteilung oder unzureichendes Kontoguthaben kennzeichnen. Eine 429-Kontingentantwort erfordert eine Abhilfe über Konto oder Tarif.

Siehe Fehler und Wiederholungen für die vollständige Wiederherstellungstabelle. Beginnen Sie bei der Integration in eine Anwendung mit den Beispielen in Programmiersprachen.

Umfang der Dokumentation

Die Referenz beschreibt die nativ gehostete Implementierung, die am 6. November 2026 überprüft und am 7. November 2026 anhand der Quelle aktualisiert wurde. Authentifizierte Produktionsprüfungen bestätigten Modellerkennung, Kontonutzung, Antworten, Chat, gepuffertes SSE, Funktionsvorschläge und deren Fortsetzung, Pro-Transkript-Chat und Quellensuche auf dem übereinstimmenden bereitgestellten Build. Ausgewählte SDK-Methoden wurden zusätzlich anhand der echten Handler mit synthetischen Abhängigkeiten geprüft. Diese Prüfungen verifizieren den ausgeführten Integrationsvertrag, nicht eine allgemeine Garantie der Modellqualität oder des Durchsatzes. Die automatische Auswahl, die ID synderesis-pro und gemeinsam genutzte Schlüssel nur für die Inferenz wurden später am 6. November 2026 nach diesen Prüfungen hinzugefügt; ihre Beschreibung hier wurde anhand des Quellcodes überprüft, nicht durch einen Live-Aufruf bestätigt.

Die Oberflächen für Konto/Sitzung, Browser-Arbeitsbereich, Gerät, Desktop, Code und MCP haben jeweils eigene Authentifizierungs- und Anwendungsverträge. Sie sind nicht automatisch mit den hier dokumentierten Kundenendpunkten austauschbar.

Kurzreferenz

Das Limit für den Antwort-Body beträgt 65536 Bytes; das Limit beträgt 921600 Bytes für Chat-Completions. Verwenden Sie genau den Endpunkt, die Methode und den Modellselektor aus der Referenz.

  • 400 unsupported_parameter: Entfernen Sie bei Chat-Completions tools aus einer Anfrage mit automatischer Auswahl oder stream aus einer Anfrage auf dem Antwortpfad.
  • 404 not_found: Prüfen Sie den Pfad.
  • 405 method_not_allowed: Prüfen Sie die HTTP-Methode; OPTIONS-Anfragen des Browsers werden nicht unterstützt.
  • 401 unauthorized: Prüfen Sie den Kundenschlüssel und senden Sie genau einen Anmeldedaten-Header.

Diese Anleitung als Markdown lesen