[SYNDERESIS / API](/de/dokumentation/) BUILD


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



# API-Referenz


Auf dieser Seite- [API-Referenz](#api-reference)- [Endpunktkarte](#endpoint-map)

- [Modelle und Serving](#models-and-serving)- [Automatische Auswahl](#automatic-selection)

- [POST /v1/answers](#post-v1answers)- [Answer-Antwort](#answer-response)

- [POST /v1/chat/completions](#post-v1chatcompletions)- [Chat-Dispatch und Verlauf](#chat-dispatch-and-history)

- [Felder für Transkript-/Tool-Anfragen](#transcripttool-request-fields)

- [Transkript-/Tool-Antwort](#transcripttool-response)

- [Unterschiede bei Antwortadapter-Anfragen](#answer-adapter-request-differences)

- [Quellensuche](#source-search)

- [GET /v1/usage](#get-v1usage)

- [GET /v1/me](#get-v1me)

- [Gemeinsames HTTP-Verhalten](#common-http-behavior)


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](/de/dokumentation/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](/de/dokumentation/limits-und-abrechnung/#shared-inference-only-keys).



## 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](#automatic-selection). 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](#automatic-selection). |

| 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](/de/dokumentation/sdks-und-beispiele/#compatibility-matrix).


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](/de/dokumentation/streaming-und-werkzeuge/#function-calling).



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



## Quellensuche


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.


[Übersicht](/de/dokumentation/)[API-Referenz →](/de/dokumentation/referenz/)


[Diesen Leitfaden als Markdown lesen](/de/docs/reference.md)
