[SYNDERESIS / API](/pl/dokumentacja/) TWORZENIE


Hostowane API dla klientów · Kontrakt przejrzany 7 listopada 2026



# SDKs i przykłady w językach programowania


Na tej stronie- [SDKs i przykłady w językach programowania](#sdks-and-language-examples)- [Macierz zgodności](#compatibility-matrix)

- [Sprawdzone wersje klientów](#client-versions-checked)

- [Python: HTTP biblioteki standardowej](#python-standard-library-http)

- [Python: Chat Completions SDK](#python-chat-completions-sdk)

- [JavaScript — Node.js fetch](#javascript-nodejs-fetch)

- [JavaScript/TypeScript: Chat Completions SDK](#javascripttypescript-chat-completions-sdk)

- [PowerShell](#powershell)

- [C#: .NET 8 lub nowszy](#c-net-8-or-later)

- [Java: Java 21 lub nowszy](#java-java-21-or-later)

- [Środowiska i wdrożenie](#environments-and-deployment)


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](/pl/dokumentacja/strumieniowanie-i-narzedzia/#the-complete-tool-loop).


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](/pl/dokumentacja/wdrozenie-produkcyjne/) omawia ponowienia, niepewność, współbieżność i monitorowanie. [Wskazówki dotyczące migracji](/pl/dokumentacja/migracja-i-pytania/) wyjaśniają różnice względem starszych przykładów i innych dostawców API.


[Przegląd](/pl/dokumentacja/)[Referencja API →](/pl/dokumentacja/specyfikacja/)


[Przeczytaj ten przewodnik jako Markdown](/pl/docs/sdk-and-examples.md)
