Zur Dokumentation springen

SYNDERESIS / API BUILD

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

API-Referenz

Auf dieser Seite

Die Basis-URL der gehosteten API ist https://www.synderesis.eu/v1. Senden Sie bei POST-Anfragen JSON mit Content-Type: application/json und authentifizieren Sie sich mit einem Kunden-API-Schlüssel-Header.

Karte der Endpunkte

Methode und Pfad Zweck Authentifizierung
GET /health Bereitschaft von Laufzeit und Datenbank; außerhalb der Basis /v1 Keine
GET /v1/models Öffentliche Produktaliase und verfügbare Metadaten API-Schlüssel
POST /v1/answers Eine Frage mit optionalem Abruf offizieller Quellen API-Schlüssel
POST /v1/chat/completions Transkript- oder Antwortadapter-Completion API-Schlüssel
GET /v1/sources/search Passagen anhand von Abfrageparametern durchsuchen API-Schlüssel
POST /v1/sources/search Passagen mit optionalen Quellenfiltern durchsuchen API-Schlüssel
GET /v1/usage Zusammenfassung der Kontozuteilung, der Nutzung und des Guthabens API-Schlüssel
GET /v1/me Profil- und Schlüsselzuordnung API-Schlüssel

Die Basis-URL enthält bereits /v1; hängen Sie /answers an, nicht /v1/answers, wenn ein Client eine Basis-URL akzeptiert. Siehe Authentifizierung für den Lebenszyklus des Schlüssels und die Header-Regeln.

Ein gemeinsam genutzter Schlüssel nur für Inferenz (Präfix sk_inf_) kann nur POST /v1/chat/completions, POST /v1/answers und GET /v1/models aufrufen. Jede andere Route antwortet mit HTTP 403 inference_scope_denied. Ein solcher Schlüssel hat eine gespeicherte Token-Obergrenze für die Lebensdauer und einen Ablaufzeitpunkt; siehe Grenzwerte und Abrechnung.

Modelle und Serving

GET /v1/models gibt ein Objekt mit object: "list" und einem data-Array zurück. Jedes Element hat id, object: "model", owned_by: "synderesis" und provider: "synderesis".

Die geprüfte Implementierung listet Folgendes auf:

Bezeichner Integrationshinweise
spark Spark-Antwortdienst. Eine explizite Anfrage verwendet ihn direkt und ruft niemals den Router auf.
pro Produktalias für Pro. Verwenden Sie genau diesen Bezeichner.
labora Aufgeführter Produktalias; die Übergabe an den Chat macht die Orchestrierungs-API von Labora nicht zugänglich.
scriptor Aufgeführter Kompatibilitäts-/Produktalias.
qwen Aufgeführter Kompatibilitäts-/Produktalias.
grok Aufgeführter Kompatibilitäts-/Produktalias.
minimax Aufgeführter Kompatibilitäts-/Produktalias.
glm Aufgeführter Kompatibilitäts-/Produktalias.
synderesis-spark Explizite Chat-Schnittstelle für Transkript und Tools; bevorzugt für Chat-SDK-Beispiele.
synderesis-pro Dokumentierte öffentliche ID für Pro; dieselbe Auswahl wie pro.
synderesis-auto Automatische Auswahl zwischen Spark und Pro. Das Weglassen von model ist dieselbe Auswahl.

Der Eintrag synderesis-spark weist außerdem context_length: 65536, max_completion_tokens: 32768 und supports_tool_calls: true aus. Dies sind ausgewiesene Modellmetadaten; Grenzen für Anfragebytes, Transkript, Ausgabe und Konto gelten weiterhin. Der Handler stellt keinen Preflight-Tokenizer-Endpunkt bereit und setzt diese ausgewiesene Kontextzahl nicht als universelle Garantie für Eingabetoken durch.

Automatische Auswahl

Bei POST /v1/answers und POST /v1/chat/completions ist das Weglassen von model dasselbe wie "model": "synderesis-auto" (Anfragealias auto). Der Alias auto wird akzeptiert, ist aber keine eigene Katalogzeile. Wenn das Routing aktiviert ist, kann ein Router-Aufruf Spark oder Pro sowie einen Aufwand auswählen; die Token des Routers werden zusammen mit der Antwort gemessen und in usage einbezogen. Befolgt wird nur eine ausgewählte Entscheidung für Spark oder Pro. Ein deaktivierter Router, ein Timeout, eine ungültige oder mit geringer Konfidenz getroffene Entscheidung oder eine Labora-Auswahl liefert Spark mit geringem Aufwand und niemals Pro.

Automatische Antworten enthalten "model": "synderesis-auto" und ein routing-Objekt: mode ist spark oder pro, status ist selected oder fallback, und effort ist der verwendete Aufwand. Explizite synderesis-spark, spark, pro und synderesis-pro behalten ihre eigenen Pfade und rufen den Router niemals auf. Bei POST /v1/chat/completions lehnt die automatische Auswahl tools und Tool-Ergebnisse mit HTTP 400 unsupported_parameter ab.

Aliasse sind stabile Produktnamen, kein Nachweis unterschiedlicher zugrunde liegender Checkpoints oder Anbieter. Die Implementierung unterstützt eine durch die Bereitstellung gesteuerte Route mit nachtrainiertem Checkpoint für berechtigte Antwortdienste und andere konfigurierte Serving-Pfade. Auf dieser API ist dafür nur eine explizite Spark- oder Pro-Anfrage an POST /v1/answers zulässig; Chat Completions, die automatische Auswahl und gemeinsam genutzte Schlüssel nur für die Inferenz wählen diese Route nicht. Wenn die Herkunft des Checkpoints, die Fallback-Richtlinie oder ein bestimmtes Modell eine Anforderung ist, bestätigen Sie die Serving-Regelung vor dem Produktionseinsatz mit Synderesis. Öffentliche Aliasse allein belegen sie nicht.

POST /v1/answers

Stellen Sie eine einzige Frage. Der Abruf offizieller Quellen ist standardmäßig aktiv. Die Anfrage ist ein JSON-Objekt von höchstens 65536 Bytes.

Feld Empfohlener Typ Verhalten
question string; erforderlich Getrimmt, nicht leer, höchstens 16,000 Zeichen.
prompt string Älterer Alias, der nur verwendet wird, wenn question fehlt. Bevorzugen Sie question.
model string Weggelassen, synderesis-auto oder auto wählt automatische Auswahl. Verwenden Sie andernfalls einen aufgeführten Alias; synderesis-pro ist dieselbe Wahl wie pro.
grounding boolean Standardmäßig aktiviert; false deaktiviert den Abruf offizieller Quellen.
retrieve_sources boolean Früherer Name für grounding. Wird ignoriert, wenn grounding vorhanden ist.
instructions string Optionale Anweisungen zu Stil oder Aufgabe. Getrimmt und auf 16,000 Zeichen gekürzt; die katholischen Antwortgrenzen bleiben angewendet.
max_tokens integer Standardmäßig 1024. Wird in eine Ganzzahl umgewandelt und auf 1–4096 begrenzt. Senden Sie eine Ganzzahl in diesem Bereich.
stream, tools — Wird ignoriert. POST /v1/answers ignoriert stream und tools; verwenden Sie die Transkript-Chat-Schnittstelle für SSE oder Funktionsaufrufe.

Die Implementierung behält die numerische Coercion für endliche Gleitkommazahlen und numerische Zeichenketten in max_tokens bei. Nicht numerische Werte, null, Container und nicht endliche Werte werden abgelehnt. Verlassen Sie sich in einer neuen Integration nicht auf die Coercion.

Verwenden Sie für grounding echte JSON-Booleans. Intern deaktivieren false, 0 und bestimmte false-ähnliche Zeichenketten grounding; Weglassen und null lassen den Abruf aktiviert. Wenn beide Namen gesendet werden, hat grounding Vorrang, auch wenn der Wert null ist. Andere nicht erkannte Felder erlangen keine Funktion allein dadurch, dass sie akzeptiert werden.

Der Abruf verwendet bis zu den ersten 8,000 Zeichen der Frage und fordert bis zu acht anfängliche Passagen an. Der Quellkontext ist auf 16,000 Zeichen begrenzt; Passagen können vor der Generierung ausgewählt oder verworfen werden. Dies begrenzt den vollständigen Prompt nicht auf 16,000 Zeichen.

Answers-Antwort

Feld Bedeutung
object catholic_ai.answer
model Öffentlicher Produktalias: synderesis-auto bei automatischer Auswahl, pro für pro oder synderesis-pro, spark für spark oder synderesis-spark. Er kann vom angeforderten Alias abweichen.
customer_id Kontokennung für den authentifizierten Aufrufer.
answer Zurückgegebener Antworttext.
structured_answer null in diesem nativen Handler. Erwarten Sie hier keine geparsten Antwortabschnitte.
structured_answer_validation unvalidated_native_gateway
grounding_status retrieved_sources_only; ein fester Status in diesem Handler, einschließlich bei Anfragen mit deaktiviertem Grounding.
source_refs Array aus Paaren von source_id und location, die als Kontext bereitgestellt werden.
retrieved_sources Quelldatensätze, die der Generierung bereitgestellt werden. Dies ist kein Verifizierungsergebnis auf Satzebene.
usage prompt_tokens, completion_tokens, total_tokens sowie usage_event_id nach gewöhnlicher Abrechnung.
retrieval_selection Enthält den Status der Zitatauswahl für eine gewöhnliche generierte Antwort.
routing Nur bei automatischer Auswahl vorhanden: mode (spark oder pro), status (selected oder fallback) und effort.

Abgerufene Datensätze enthalten source_id, location, title, url, publisher, source_type, summary und text sowie zutreffende Quellenmetadaten zur Quellenautorität und Provenienz. Text ist auf 2,400 Zeichen je zurückgegebenem Datensatz begrenzt. Zusätzliche Metadaten können erscheinen.

Die Nutzung kann die Arbeit zur Passagenauswahl und, bei automatischer Auswahl, den Router-Aufruf sowie die Antwortgenerierung umfassen. Die Nutzung ist nicht notwendigerweise nur die Tokenanzahl der für den Benutzer sichtbaren Frage und Antwort. Die Nutzung des Anbieters wird verwendet, wenn sie gültig ist; begrenzte Schätzungen sind möglich.

Die exakte Konnektivitätsfrage Reply with exactly one word: ok hat einen speziellen authentifizierten Antwortpfad. Dessen Ausgabe ist kein Test der Modellqualität, des Abrufs oder der Abrechnung. Zurückgegeben werden weder usage_event_id noch retrieval_selection. Ein gemeinsamer Schlüssel nur für die Inferenz erhält diese Abkürzung nicht; seine Probe wird als gewöhnliche Anfrage gemessen. Verwenden Sie eine gewöhnliche Frage, um eine echte Generierung zu testen.

POST /v1/chat/completions

Die Anfrage ist ein JSON-Objekt von höchstens 921600 Bytes für chat completions. Der Modellalias und die tool-bezogenen Felder wählen einen von zwei Verarbeitungspfaden.

Chat-Dispatch und Verlauf

Anfrage Behandlung
model ist synderesis-spark Transkript-/Tool-Pfad, mit oder ohne Tools.
model ist spark, pro oder synderesis-pro, und tools ist vorhanden (einschließlich eines leeren Arrays) oder das Transkript enthält eine tool-Rolle oder tool_calls Transkript-/Tool-Pfad.
model weggelassen, auto oder synderesis-auto, mit Tools oder Tool-Verlauf 400 unsupported_parameter.
Jedes andere Modell mit Tools oder Tool-Verlauf, zum Beispiel labora 400 unsupported_model.
model weggelassen, auto oder synderesis-auto, ohne Tools und ohne Tool-Verlauf Nimmt den Antwortpfad mit automatischer Auswahl.
spark, pro, synderesis-pro oder ein anderer akzeptierter Alias, ohne Tools und ohne Tool-Verlauf Nimmt den Antwortpfad: verwendet die letzte user-Nachricht und die system-Nachrichten.

Senden Sie für ein Pro-Transkript ohne Funktionsdefinitionen "model":"pro","tools":[] (oder synderesis-pro). Um den Konversationsverlauf zu bewahren, wählen Sie den Transkriptpfad bewusst. Der Antwortadapter sendet frühere user-/assistant-Konversationsrunden nicht an die Generierung.

Felder der Transkript-/Tool-Anfrage

Feld Typ Verhalten
model string synderesis-spark oder, wenn tools vorhanden ist, spark, pro oder synderesis-pro.
messages array; erforderlich 1–255 Nachrichten mit den Rollen system, developer, user, assistant oder tool.
messages[].content string, Array von Textteilen oder null Textteile verwenden type=text und ein Textfeld vom Typ string. Akzeptiert werden nur Textteile. null ist für eine assistant-Nachricht mit Tool-Aufruf gültig.
tools array Optionale Funktionsdefinitionen; ein leeres Array wählt für unterstützte Aliase den Transkriptpfad.
tool_choice string oder Objekt einer benannten Funktion Standardmäßig auto; akzeptiert werden none, required oder eine benannte übergebene Funktion.
parallel_tool_calls boolean Standardmäßig true.
max_completion_tokens integer Hat Vorrang vor max_tokens. Standardmäßig 8192; gültiger Bereich 1–32768. Ein explizites null verwendet den Standardwert.
max_tokens integer Wird verwendet, wenn max_completion_tokens fehlt; derselbe Bereich und Standardwert.
stream boolean Standardmäßig false. true gibt nach der Generierung gepuffertes SSE zurück.
stream_options object include_usage=true fügt beim Streaming einen abschließenden usage-Chunk hinzu.
n number Nur 1 wird unterstützt.
response_format — Muss auf diesem Pfad weggelassen werden oder null sein. Modi für strukturierte Ausgaben werden hier nicht unterstützt.

Zusätzliche Felder für Sampling, seed, user, metadata und Persistenz werden von diesem Handler nicht weitergeleitet. Dass sie angenommen werden, bedeutet nicht, dass sie das Modellverhalten beeinflussen. Sehen Sie die SDK-Kompatibilitätsmatrix.

Das vollständige Transkript wird bei jedem Aufruf erneut gesendet. Alle ausstehenden Tool-Aufrufe müssen entsprechende Tool-Ergebnisse haben, bevor die nächste gewöhnliche Nachricht folgt. Validieren Sie die vollständige Sequenz und folgen Sie der Tool-Schleife.

Transkript-/Tool-Antwort

Eine Antwort ohne Streaming enthält:

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

Die Werte sind veranschaulichend. Die Antwort model ist synderesis-spark für die Spark-Aliasse und pro für pro oder synderesis-pro. Die assistant-Nachricht kann stattdessen tool_calls und nullfähigen content enthalten. Ein Tool-Aufruf hat id, type=function sowie function.name und function.arguments; arguments ist eine JSON-Zeichenkette, kein dekodiertes Objekt. Abschlussgründe können stop, length und tool_calls umfassen. Behandeln Sie unbekannte künftige Werte, ohne die Antwort zu verwerfen.

Eine anbieterabhängige assistant-Zeichenkette reasoning_content kann für die Fortsetzung des Transkripts beibehalten werden. Behandeln Sie sie als optionales Transportfeld; verlassen Sie sich nicht auf ihre Verfügbarkeit und zeigen oder protokollieren Sie sie nicht standardmäßig.

Unterschiede bei Anfragen des Answer-Adapters

Der Adapter übernimmt die letzte user-Nachricht als Frage und verkettet den Inhalt der system-Nachrichten als Anweisungen. Frühere Gesprächsrunden und Anweisungen der Rolle developer werden nicht als vollständiges Transkript weitergeleitet. Bei automatischer Auswahl werden bis zu zwei frühere user-Runden (die ersten 500 Zeichen jeder Runde) nur an den Router gegeben, um eine Folgeanfrage zu klassifizieren; sie gelangen nicht zur Antwortgenerierung und werden nicht gespeichert.

max_tokens hat den Standardwert 4096 und wird auf 1–4096 begrenzt, entsprechend der Coercion des Answer-Endpunkts. max_completion_tokens steuert diesen Adapter nicht. stream: true gibt 400 unsupported_parameter zurück. Der Adapter kann grounding/retrieve_sources wie answers verwenden.

Seine Antwort ist kleiner: id=chatcmpl-native, object, model, choices und usage sowie routing bei automatischer Auswahl. model ist synderesis-auto bei automatischer Auswahl und andernfalls der öffentliche Alias, zum Beispiel spark oder pro. created ist nicht enthalten. Seine choices enthalten eine assistant-Zeichenkette und finish_reason=stop; verwenden Sie diesen festen stop-Wert nicht als Nachweis dafür, dass die Generierung nicht abgeschnitten wurde. Zitations-/Quellenfelder aus der Answer-Antwort sind in der angepassten Chat-Antwort nicht enthalten.

Verwenden Sie GET /v1/sources/search?query=...&limit=6 oder POST /v1/sources/search mit einem JSON-Objekt. Eine Authentifizierung ist erforderlich.

Feld Wo Verhalten
query GET-Query oder POST-Body Nicht leere Suchzeichenfolge, höchstens 8,000 Zeichen.
q GET-Query oder POST-Body Legacy-Fallback, wenn query fehlt. Bevorzugen Sie query.
limit GET-Query oder POST-Body Ganzzahl 1–20; Standard ist 6.
source_ids POST-Body Bis zu 100 IDs, jeweils höchstens 256 Zeichen. Ein ID-String wird ebenfalls akzeptiert; bevorzugen Sie ein Array.
source_id POST-Body Kompatibilitätsname im Singular, mit Vorrang vor source_ids.

Ein GET-Query-Parameter source_ids ist kein dokumentierter Filter; verwenden Sie POST zum Filtern. POST verwendet das gewöhnliche Body-Limit von 65,536 Byte.

Die Antwort enthält object=source_search, query und data. Jeder data-Eintrag enthält source_id, location, title, url, publisher, source_type, chunk_kind, paragraph_index, summary und text. summary ist auf 1,200 Zeichen begrenzt und text auf 4,000. Dies sind abgerufene Passagen; respektieren Sie die Rechte ihrer ursprünglichen Herausgeber.

Eine Suche reserviert Kontingent und zeichnet bei Erfolg ein Nutzungsereignis des Kontos mit null Generierungstoken auf. Null Generierungstoken bedeutet nicht, dass Anfragekontingente umgangen werden. Suchfehler geben derzeit bei mehreren Backend- oder Kontingentfehlern service_unavailable zurück; gehen Sie nicht davon aus, dass jede Kontingentursache an diesem Endpunkt als 429 ausgewiesen wird.

GET /v1/usage

Dieser Endpunkt meldet kontoweite Werte, einschließlich der Aktivität, die anderen Schlüsseln und der Browsernutzung zugerechnet wird. Er gibt kein nach Anfragen aufgeschlüsseltes Abrechnungsjournal zurück.

Feld Bedeutung
object synderesis.usage
customer_id Bezeichner des Kontos.
api_key_prefix Präfix des vorgelegten Schlüssels; bei ausschließlich sitzungsbasiertem Zugriff weggelassen.
used_tokens Nutzung der Zuteilung über Zeiträume hinweg, einschließlich ausstehender reservierter Token.
initial_allocation Die einmalige anfängliche Tokenzuteilung der Kontoautorität.
remaining_tokens max(0, initial_allocation - used_tokens).
allocation_exhausted Zeigt die Erschöpfung an, wenn das Konto nicht durch eine bezahlte oder unentgeltliche Berechtigung freigegeben ist.
paid Ob eine aktuelle bezahlte Berechtigung anerkannt wird.
complimentary Ob eine unentgeltliche Zuwendung anerkannt wird.
credit_used_eur Informatorischer Betrag des verbrauchten Guthabens in Euro.
credit_remaining_eur Informatorischer Guthabenstand in Euro.

Token-Felder sind keine monatlichen Auffüllzähler. Ein bezahltes Konto kann remaining_tokens=0 haben, während die Beschränkung der kostenlosen Zuteilung aufgehoben wurde. Guthabenfelder sind informatorisch und können auf null zurückfallen, wenn die Abrechnungsübersicht nicht gelesen werden kann; nutzen Sie Konto/Support für den Abgleich.

GET /v1/me

Ein authentifizierter Kundenschlüssel kann das eigene Profil lesen. Die Antwort enthält object=synderesis.me, customer_id, email, plan, plan_label, api_key_prefix, name, organization, chat_access, service_available und service_live.

Service-Flags und Planbezeichnungen sind Anwendungsmetadaten; sie verleihen keine Privilegien zur Kontoverwaltung und ersetzen nicht die Autorisierungsentscheidung des tatsächlichen Endpunkts. Behandeln Sie Profilwerte als personenbezogene Daten.

Allgemeines HTTP-Verhalten

Native API-Antworten enthalten die Sicherheitsheader X-Request-ID und no-store. Verwenden Sie error.request_id und den Antwortheader, wenn Sie ein Problem melden. Eine übergebene X-Request-ID wird nur als 1–128 ASCII-Buchstaben, Ziffern, Punkte, Unterstriche, Doppelpunkte oder Bindestriche akzeptiert; ungültige Werte werden ersetzt.

Unbekannte Pfade geben 404 not_found zurück. Nicht unterstützte Methoden geben 405 method_not_allowed zurück, mit einem Allow-Header, sofern zutreffend. OPTIONS ist enthalten, weil die Kunden-API CORS nicht aktiviert.

In dieser Laufzeit gibt es weder ein allgemein vom Server veröffentlichtes /openapi.json noch eine Swagger UI. Diese Referenz und die entsprechende Implementierung im Repository definieren die geprüfte Oberfläche.

Diesen Leitfaden als Markdown lesen