SYNDERESIS / API ENTWICKLUNG
Gehostete Kunden-API · Vertrag geprüft am 7. November 2026
SDKs und Beispiele für Programmiersprachen
Auf dieser Seite
Verwenden Sie einen Standard-HTTP-Client oder konfigurieren Sie einen getesteten Chat-Completions-Client mit der Basis-URL und dem Schlüssel von Synderesis. Diese Beispiele rufen die dokumentierten Kundenendpunkte von einem Server aus auf.
Kompatibilitätsmatrix
| Funktion | Transkript-/Tool-Chat | Antwortadapter-Chat |
|---|---|---|
| Bevorzugter Selektor | synderesis-spark; pro oder synderesis-pro mit tools=[] für ein Pro-Transkript | spark, pro oder ein weggelassenes Modell für die automatische Auswahl |
| Vollständig bereitgestelltes Transkript | Ja, innerhalb der Grenzen für Nachricht und Body | Letzte Benutzernachricht sowie Systemanweisungen |
| Nachrichten mit der Rolle developer | Akzeptiert | Nicht als Anweisungen der Rolle developer weitergeleitet |
| Textinhaltsteile | Akzeptiert und als Text zusammengefügt | Verwenden Sie das nicht; senden Sie den Inhalt als Zeichenkette |
| Funktions-Tools | Unterstützt für die dokumentierten Aliasse | Das Vorhandensein wählt den Tool-Pfad für spark, pro und synderesis-pro; die automatische Auswahl lehnt sie mit 400 unsupported_parameter ab |
| max_completion_tokens | Berücksichtigt; hat Vorrang | Nicht verwendet |
| max_tokens | Berücksichtigt, wenn max_completion_tokens fehlt | Berücksichtigt/begrenzt |
| stream=true | Gepuffertes SSE nach der Generierung | 400 unsupported_parameter |
| stream_options.include_usage | Fügt einen usage-Chunk hinzu, wenn der Wert genau true ist | Keine Streaming-Unterstützung |
| n | Nur 1 | Keine Multi-Completion-Schnittstelle |
| response_format | Nur weggelassen/null | Nicht als Steuerung für strukturierte Ausgabe weitergeleitet |
| temperature, top_p, seed, penalties | Von diesem Handler nicht weitergeleitet | Nicht als Sampling-Steuerungen weitergeleitet |
| store, metadata, user | Erstellen Sie keine Persistenz-/Metadatenfunktionen | Erstellen Sie keine Persistenz-/Metadatenfunktionen |
| Responses-/Assistants-/embeddings-/audio-/files-APIs | Außerhalb dieser dokumentierten Oberfläche | Außerhalb dieser dokumentierten Oberfläche |
Ein unterstütztes Format bedeutet keine vollständige Kompatibilität mit allen OpenAI-Endpunkten, Modellfunktionen oder SDK-Methoden. Deaktivieren oder prüfen Sie SDK-Wiederholungen ausdrücklich, weil mehrdeutige Fehlschläge die Arbeit bereits verbraucht haben können.
Geprüfte Clientversionen
OpenAI Python 3.46.0 und OpenAI JavaScript/TypeScript 7.53.0 wurden auf die Erstellung von Chat Completions, gepuffertes SSE mit usage, den Pro-Transkriptselektor und das typisierte Parsen von 400-Fehlern geprüft.
Diese Prüfungen verwendeten den echten HTTP-Handler von Synderesis mit synthetischen Abhängigkeiten für Identität, Kontingent und Generierung. Sie verifizieren die Serialisierung und das Parsen des Clients anhand dieses Vertrags; sie sind weder ein Live-Test der Modellqualität noch eine Garantie für ungeprüfte SDK-Versionen oder -Funktionen.
Python: HTTP der Standardbibliothek
Speichern Sie als example.py. Python 3.12 genügt; dieses Beispiel hat keine Client-Abhängigkeit von Drittanbietern.
import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen
key = os.environ["SYNDERESIS_API_KEY"]
body = {
"model": "spark",
"question": "Explain human dignity in two sentences.",
"grounding": True,
"max_tokens": 1024,
}
request = Request(
"https://www.synderesis.eu/v1/answers",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {key}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urlopen(request, timeout=60) as response:
payload = json.load(response)
print(payload["answer"])
print(payload["usage"])
except HTTPError as error:
payload = json.loads(error.read().decode("utf-8"))
detail = payload.get("error", {})
raise RuntimeError(
f"Synderesis HTTP {error.code}: {detail.get('code')}; "
f"request_id={detail.get('request_id')}"
) from None
Führen Sie python example.py aus, nachdem die Umgebungsvariable injiziert wurde.
Python: Chat Completions SDK
Installieren Sie die geprüfte Version:
python -m pip install openai==3.46.0
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["SYNDERESIS_API_KEY"],
base_url="https://www.synderesis.eu/v1",
timeout=120.0,
max_retries=0,
)
completion = client.chat.completions.create(
model="synderesis-spark",
messages=[{"role": "user", "content": "Explain human dignity briefly."}],
max_completion_tokens=1024,
)
message = completion.choices[0].message
print(message.content or "")
print(completion.usage)
Eine Tool-Call-Nachricht kann den Inhalt null haben; prüfen Sie tool_calls und autorisieren bzw. führen Sie Funktionen in Ihrer Anwendung aus. Siehe die Tool-Schleife.
Erstellen Sie für einen Stream die Anfrage mit stream=True und stream_options={"include_usage": True}; durchlaufen Sie die zurückgegebenen Chunks und behandeln Sie leere choices im usage-Chunk.
JavaScript — fetch unter Node.js
Speichern Sie als example.mjs und führen Sie node example.mjs unter Node.js 20 oder höher aus. Dies ist serverseitiger Code.
const key = process.env.SYNDERESIS_API_KEY;
if (!key) throw new Error("Set SYNDERESIS_API_KEY in this server process.");
const response = await fetch(
"https://www.synderesis.eu/v1/chat/completions",
{
method: "POST",
headers: {
Authorization: `Bearer ${key}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "synderesis-spark",
messages: [{ role: "user", content: "Explain human dignity briefly." }],
max_completion_tokens: 1024,
}),
signal: AbortSignal.timeout(120_000),
},
);
const payload = await response.json();
if (!response.ok) {
throw new Error(
`Synderesis HTTP ${response.status}: ${payload.error?.code}; request_id=${payload.error?.request_id}`,
);
}
console.log(payload.choices[0].message.content ?? "");
console.log(payload.usage);
Fügen Sie diesen Code und einen echten Schlüssel nicht in eine Webseite ein. Rufen Sie aus dem Browser Ihr eigenes authentifiziertes Backend auf.
JavaScript/TypeScript: Chat Completions SDK
Installieren Sie:
npm install openai@7.53.0
import OpenAI from "openai";
const key = process.env.SYNDERESIS_API_KEY;
if (!key) throw new Error("Set SYNDERESIS_API_KEY.");
const client = new OpenAI({
apiKey: key,
baseURL: "https://www.synderesis.eu/v1",
timeout: 120_000,
maxRetries: 0,
});
const stream = await client.chat.completions.create({
model: "synderesis-spark",
messages: [{ role: "user", content: "Explain human dignity briefly." }],
max_completion_tokens: 1024,
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) process.stdout.write(text);
if (chunk.usage) console.error(JSON.stringify(chunk.usage));
}
process.stdout.write("\n");
Der Server puffert diesen Stream, bis die Generierung abgeschlossen ist. Lassen Sie für eine Antwort ohne Streaming stream und stream_options weg und lesen Sie completion.choices[0].message.
PowerShell
Die Umgebungsvariable wird im aktuellen Prozess gelesen. ConvertTo-Json erzeugt den Anfragekörper ohne shellspezifisches Quoting von JSON.
if (-not $env:SYNDERESIS_API_KEY) {
throw "Set SYNDERESIS_API_KEY in this process."
}
$synderesisBody = @{
model = "spark"
question = "Explain human dignity in two sentences."
grounding = $true
max_tokens = 1024
} | ConvertTo-Json -Depth 8
$synderesisRequest = @{
Method = "Post"
Uri = "https://www.synderesis.eu/v1/answers"
Headers = @{ Authorization = "Bearer $env:SYNDERESIS_API_KEY" }
ContentType = "application/json; charset=utf-8"
Body = [Text.Encoding]::UTF8.GetBytes($synderesisBody)
TimeoutSec = 120
}
$synderesisResult = Invoke-RestMethod @synderesisRequest
$synderesisResult.answer
$synderesisResult.usage
C#: .NET 8 oder höher
Erstellen Sie ein Konsolenprojekt und ersetzen Sie Program.cs durch dieses vollständige HTTP-Beispiel.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
string key = Environment.GetEnvironmentVariable("SYNDERESIS_API_KEY")
?? throw new InvalidOperationException("Set SYNDERESIS_API_KEY.");
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", key);
using var response = await client.PostAsJsonAsync(
"https://www.synderesis.eu/v1/answers",
new {
model = "spark",
question = "Explain human dignity in two sentences.",
grounding = true,
max_tokens = 1024
}
);
string text = await response.Content.ReadAsStringAsync();
using var payload = JsonDocument.Parse(text);
if (!response.IsSuccessStatusCode)
{
var error = payload.RootElement.GetProperty("error");
throw new InvalidOperationException(
$"Synderesis HTTP {(int)response.StatusCode}; " +
$"code={error.GetProperty("code").GetString()}; " +
$"request_id={error.GetProperty("request_id").GetString()}"
);
}
Console.WriteLine(payload.RootElement.GetProperty("answer").GetString());
Java: Java 21 oder höher
Speichern Sie als Example.java. Der integrierte HTTP-Client sendet denselben JSON-Vertrag; das Beispiel gibt die JSON-Antwort aus, damit die JSON-Bibliothek Ihrer Anwendung answer und usage parsen kann.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class Example {
public static void main(String[] args) throws Exception {
String key = System.getenv("SYNDERESIS_API_KEY");
if (key == null || key.isBlank()) {
throw new IllegalStateException("Set SYNDERESIS_API_KEY.");
}
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(15)).build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://www.synderesis.eu/v1/answers"))
.timeout(Duration.ofSeconds(120))
.header("Authorization", "Bearer " + key)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{"model":"spark","question":"Explain human dignity briefly.",
"grounding":true,"max_tokens":1024}
"""))
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString()
);
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new IllegalStateException(
"Synderesis HTTP " + response.statusCode() +
"; request_id=" +
response.headers().firstValue("x-request-id").orElse("unavailable")
);
}
System.out.println(response.body());
}
}
Führen Sie java Example.java aus. Produktivanwendungen sollten die Antwort mit der von ihnen gewählten JSON-Bibliothek parsen und Fehlerinhalte geschwärzt lassen.
Umgebungen und Bereitstellung
Verwenden Sie die Geheimnisverwaltung der Server-Laufzeitumgebung für Entwicklung, CI, Container und Cloud-Bereitstellungen. Das öffentliche Präfix für Umgebungsvariablen eines Browser-Frameworks darf niemals für einen Kundenschlüssel verwendet werden.
Berücksichtigen Sie bei serverlosen Funktionen ausdrücklich Kaltstarts und Zeitüberschreitungen der Plattform. Injizieren Sie bei Containern Geheimnisse zur Laufzeit, statt sie in Image-Layer einzubacken. Testen Sie genau die Kombination aus Laufzeitumgebung, Clientversion und Proxy, die Sie bereitstellen.
Der Produktionsleitfaden behandelt Wiederholungen, Unsicherheit, Nebenläufigkeit und Überwachung. Die Migrationshinweise erläutern Unterschiede zu älteren Beispielen und anderen API-Anbietern.