SynapseX Python SDK

This page gets the official SynapseX Python client running in your project. At the end you will have installed the package, made a chat completion in three lines, streamed a response, and wired up typed error handling.

Install

pip install synapsex-platform

Python 3.10 or newer. Then import from synapsex_platform (underscore):

from synapsex_platform import LLMClient

Install the right package. pip install synapsex and from synapsex import ... refer to a different, unrelated package that is not this SDK and will not work against the SynapseX Platform API. The package name is synapsex-platform and the import name is synapsex_platform.

Construct the client

from synapsex_platform import LLMClient
 
client = LLMClient()

With no arguments, LLMClient() reads:

You can also pass them explicitly:

client = LLMClient(api_key="sk-synapsex-YOUR-API-KEY", timeout=60.0)

If no key is found the constructor raises immediately rather than failing on the first request. The client refuses a non-HTTPS base URL — http:// is allowed only for localhost, 127.0.0.1 and ::1 — so the key can never be sent in the clear. The key is never logged and never appears in repr().

LLMClient is also a context manager, which closes the connection pool for you:

with LLMClient() as client:
    ...

Your first script

from synapsex_platform import LLMClient
 
client = LLMClient()  # reads SYNAPSEX_API_KEY
 
response = client.chat_completions(
    model="synapsex-forge-code-14b-v1",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "In one sentence, what is superposition?"},
    ],
)
 
print(response["choices"][0]["message"]["content"])

chat_completions() returns the parsed chat.completion dictionary, so the assistant text is at response["choices"][0]["message"]["content"].

Streaming

Pass stream=True and iterate. The SDK yields parsed chat.completion.chunk dictionaries and ends the iteration at the terminating [DONE] frame, so you never handle the sentinel yourself:

from synapsex_platform import LLMClient
 
client = LLMClient()
 
stream = client.chat_completions(
    model="synapsex-forge-code-14b-v1",
    messages=[{"role": "user", "content": "Count from 1 to 5."}],
    stream=True,
)
 
for chunk in stream:
    choices = chunk.get("choices") or []
    if not choices:
        continue
    piece = choices[0].get("delta", {}).get("content")
    if piece:
        print(piece, end="", flush=True)
print()

Pick a model at startup with list_models()

from synapsex_platform import LLMClient
 
client = LLMClient()
 
models = client.list_models()
for model in models.get("data", []):
    print(model["id"], model.get("context_window"))

list_models() returns the parsed {"object": "list", "data": [...]} response. Note that this is the SynapseX model catalog, not a per-key permission list: an id can be listed here and still be refused with HTTP 403 on /chat/completions. See Models.

A safe startup check is to assert your intended id is still in the catalog, and fail loudly rather than substituting an id you have not verified:

PREFERRED = "synapsex-forge-code-14b-v1"
 
catalog = {m["id"] for m in client.list_models().get("data", [])}
if PREFERRED not in catalog:
    raise SystemExit(f"{PREFERRED} is no longer in the SynapseX catalog: {sorted(catalog)}")

Typed errors

Each failing status raises a specific exception. All of them subclass APIError, which subclasses SynapseXError, and carry status_code and the parsed payload:

from synapsex_platform import (
    LLMClient,
    AuthenticationError,
    InsufficientCreditsError,
    PermissionDeniedError,
    RateLimitError,
    APIError,
)
 
client = LLMClient()
 
try:
    response = client.chat_completions(
        model="synapsex-forge-code-14b-v1",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except AuthenticationError:
    raise SystemExit("Check SYNAPSEX_API_KEY - the key is missing or invalid.")
except InsufficientCreditsError:
    raise SystemExit("Out of credits. Top up the workspace before retrying.")
except PermissionDeniedError as exc:
    raise SystemExit(f"Not permitted: {exc}")
except RateLimitError:
    ...  # back off and retry
except APIError as exc:
    raise SystemExit(f"Request failed ({exc.status_code}): {exc}")

Full guidance per status is on API errors.

Passing extra parameters

chat_completions() accepts temperature, top_p and max_tokens as named arguments, and these are honoured:

response = client.chat_completions(
    model="synapsex-forge-code-14b-v1",
    messages=[{"role": "user", "content": "Hello!"}],
    temperature=0.7,
    top_p=1.0,
    max_tokens=128,
)

The method also accepts arbitrary extra keyword arguments and puts them in the request body — but the API does not forward anything beyond model, messages, stream, temperature, top_p and max_tokens, so those extra arguments have no effect. Do not rely on them. See Chat completions for the supported field list.

JavaScript and TypeScript

There is no published SynapseX JavaScript or TypeScript SDK today. JavaScript users should use the openai npm package (or plain fetch) against the same base URL — see Use SynapseX with OpenAI-compatible clients.

Related

• Chat completions and streaming
• Authenticate with a SynapseX API key
• API errors and how to handle them