SYNDERESIS / API TWORZENIE
Hostowane API dla klientów · Kontrakt przejrzany 7 listopada 2026
SDKs i przykłady w językach programowania
Na tej stronie
Użyj standardowego klienta HTTP lub skonfiguruj przetestowanego klienta Chat Completions z bazowym adresem URL Synderesis i kluczem Synderesis. Te przykłady wywołują z serwera udokumentowane punkty końcowe dla klientów.
Macierz zgodności
| Funkcja | Czat transkryptu/narzędzi | Czat adaptera odpowiedzi |
|---|---|---|
| Preferowany selektor | synderesis-spark; pro lub synderesis-pro z tools=[] dla transkryptu Pro | spark, pro lub pominięty model do automatycznego wyboru |
| Pełny dostarczony transkrypt | Tak, w granicach wiadomości i body | Ostatnia wiadomość użytkownika oraz instrukcje systemowe |
| Wiadomości z rolą developer | Akceptowane | Nieprzekazywane jako instrukcje roli developer |
| Tekstowe części treści | Akceptowane i łączone jako tekst | Nie używaj; wysyłaj treść jako ciąg znaków |
| Narzędzia funkcyjne | Obsługiwane dla udokumentowanych aliasów | Obecność wybiera ścieżkę narzędzi dla spark, pro i synderesis-pro; automatyczny wybór odrzuca je z 400 unsupported_parameter |
| max_completion_tokens | Uwzględniane; ma pierwszeństwo | Nieużywane |
| max_tokens | Uwzględniane, gdy max_completion_tokens jest nieobecne | Uwzględniane/ograniczane |
| stream=true | Buforowane SSE po wygenerowaniu | 400 unsupported_parameter |
| stream_options.include_usage | Dodaje chunk usage, gdy wartość jest dokładnie true | Brak obsługi streamingu |
| n | Tylko 1 | To nie jest interfejs multi-completion |
| response_format | Tylko pominięte/null | Nieprzekazywane jako sterowanie ustrukturyzowanym wyjściem |
| temperature, top_p, seed, penalties | Nieprzekazywane przez ten handler | Nieprzekazywane jako elementy sterujące samplingiem |
| store, metadata, user | Nie twórz funkcji persystencji/metadanych | Nie twórz funkcji persystencji/metadanych |
| Interfejsy API Responses/Assistants/embeddings/audio/files | Poza tą udokumentowaną powierzchnią | Poza tą udokumentowaną powierzchnią |
Obsługiwany format nie oznacza pełnej kompatybilności ze wszystkimi endpointami OpenAI, funkcjami modeli ani metodami SDK. Wyraźnie wyłącz lub sprawdź ponowienia SDK, ponieważ niejednoznaczne niepowodzenia mogły już zużyć pracę.
Sprawdzone wersje klienta
OpenAI Python 3.46.0 i OpenAI JavaScript/TypeScript 7.53.0 sprawdzono pod kątem tworzenia Chat Completions, buforowanego SSE z usage, selektora transkrypcji Pro oraz typowanego parsowania błędów 400.
Te sprawdzenia używały rzeczywistego handlera HTTP Synderesis z syntetycznymi zależnościami tożsamości, limitu i generowania. Weryfikują one serializację i parsowanie klienta względem tego kontraktu; nie są testem jakości modelu na żywo ani gwarancją dla niesprawdzonych wersji lub funkcji SDK.
Python: HTTP biblioteki standardowej
Zapisz jako example.py. Wystarczy Python 3.12; ten przykład nie ma zależności od klienta zewnętrznego.
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
Uruchom python example.py po wstrzyknięciu zmiennej środowiskowej.
Python: Chat Completions SDK
Zainstaluj sprawdzoną wersję:
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)
Wiadomość wywołania narzędzia może mieć treść null; sprawdź tool_calls i autoryzuj/wykonaj funkcje w swojej aplikacji. Zobacz pętlę narzędzi.
Dla strumienia utwórz żądanie ze stream=True i stream_options={"include_usage": True}; iteruj zwrócone chunki i obsłuż puste choices w chunku usage.
JavaScript — fetch w Node.js
Zapisz jako example.mjs i uruchom node example.mjs w Node.js 20 lub nowszym. To kod po stronie serwera.
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);
Nie umieszczaj tego kodu ani prawdziwego klucza na stronie internetowej. Wywołuj z przeglądarki własny uwierzytelniony backend.
JavaScript/TypeScript: Chat Completions SDK
Zainstaluj:
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");
Serwer buforuje ten strumień do zakończenia generowania. W przypadku odpowiedzi bez strumieniowania pomiń stream i stream_options oraz odczytaj completion.choices[0].message.
PowerShell
Zmienna środowiskowa jest odczytywana w bieżącym procesie. ConvertTo-Json tworzy treść żądania bez specyficznego dla powłoki cytowania 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 lub nowszy
Utwórz projekt konsolowy i zastąp Program.cs tym kompletnym przykładem HTTP.
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 lub nowszy
Zapisz jako Example.java. Wbudowany klient HTTP wysyła ten sam kontrakt JSON; przykład wypisuje odpowiedź JSON, aby biblioteka JSON Twojej aplikacji mogła sparsować answer i usage.
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());
}
}
Uruchom java Example.java. Aplikacje produkcyjne powinny parsować odpowiedź przy użyciu wybranej przez siebie biblioteki JSON i pozostawiać treści błędów w postaci zredagowanej.
Środowiska i wdrażanie
Używaj menedżera sekretów środowiska uruchomieniowego serwera na potrzeby rozwoju, CI, kontenerów i wdrożeń w chmurze. Publicznego prefiksu zmiennych środowiskowych frameworka przeglądarkowego nigdy nie wolno używać do klucza klienta.
W przypadku funkcji bezserwerowych wyraźnie uwzględnij zimne starty i limity czasu platformy. W przypadku kontenerów wstrzykuj sekrety w czasie działania, zamiast wbudowywać je w warstwy obrazu. Przetestuj dokładnie kombinację środowiska uruchomieniowego, wersji klienta i proxy, którą wdrażasz.
Przewodnik produkcyjny omawia ponowienia, niepewność, współbieżność i monitorowanie. Wskazówki dotyczące migracji wyjaśniają różnice względem starszych przykładów i innych dostawców API.