Zur Dokumentation springen

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.

Lesen Sie diesen Leitfaden als Markdown