Skip to Content
Platform APIOpenAI compatibility

Use SynapseX with OpenAI-compatible clients

This page migrates an existing OpenAI-shaped application onto SynapseX without rewriting it. At the end you will have the stock openai package talking to SynapseX models, and a checklist of exactly what does and does not carry over.

The concrete value: no rewrite, no vendor SDK required.

The migration is two lines

base_url = https://platform.synapsex.ai/api/v1
api_key  = sk-synapsex-YOUR-API-KEY

That is the whole change. The wire format is OpenAI-compatible, so the request body and the response object are shapes your client already knows. Error bodies are mostly OpenAI-shaped too — with one exception covered below.

Python with the stock openai package

from openai import OpenAI
 
client = OpenAI(
    api_key="sk-synapsex-YOUR-API-KEY",
    base_url="https://platform.synapsex.ai/api/v1",
)
 
response = client.chat.completions.create(
    model="synapsex-forge-code-14b-v1",
    messages=[{"role": "user", "content": "Hello!"}],
)
 
print(response.choices[0].message.content)

Streaming works the same way — pass stream=True and iterate the chunks.

Node with fetch

There is no published SynapseX JavaScript SDK. Use the openai npm package against the same base URL, or call the endpoint directly:

const response = await fetch(
  "https://platform.synapsex.ai/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SYNAPSEX_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "synapsex-forge-code-14b-v1",
      messages: [{ role: "user", content: "Hello!" }],
    }),
  },
);
 
const data = await response.json();
console.log(data.choices[0].message.content);

Configuring a third-party tool

Many tools have a settings screen asking for an “OpenAI-compatible base URL” and an API key. Paste these exact values:

Field the tool asks forValue to paste
Base URL / API base / endpointhttps://platform.synapsex.ai/api/v1
API key / tokenyour sk-synapsex-… key
Modelsynapsex-forge-code-14b-v1 to start with

Some tools append /v1 themselves. If the tool builds a URL ending in /api/v1/v1/chat/completions, drop the /api/v1 suffix from what you paste and let the tool add it — the path that must be reached is https://platform.synapsex.ai/api/v1/chat/completions.

Compatibility boundaries

Check this list before you migrate, not at runtime.

Supported through this base URL:

  • Request fields model, messages, stream, temperature, top_p, max_tokens
  • Server-sent-event streaming with chat.completion.chunk frames and a final data: [DONE]
  • The OpenAI chat.completion response shape
  • The OpenAI-style error envelope, for errors raised by the API itself

Not supported through this base URL:

  • tools / function calling, and tool_choice
  • response_format / JSON mode
  • seed, stop, n, logprobs
  • presence_penalty, frequency_penalty, user
  • Embeddings, images, audio, assistants, batches

Unsupported request fields are not rejected — they are dropped. A call that passes response_format will succeed and ignore it. If your application depends on any of the above, that dependency must be removed or reimplemented before you switch.

Error-shape compatibility

Errors raised by the API itself come back in the OpenAI envelope:

{"error":{"message":"…","type":"…"}}

with the types authentication_error, permission_error, insufficient_quota, invalid_request_error and server_error. Existing OpenAI error handling mostly works unchanged.

One exception to plan for: when the model gateway behind the API rejects a request — a model id that is not available to API keys, or a rate limit — its own response is forwarded verbatim, with its original status code and a body shaped {"detail": "…"} rather than {"error": {...}}. Branch on the HTTP status code, and read error.message when present, falling back to detail.

The one SynapseX-specific behaviour to add is the 402 semantics: SynapseX is prepaid, and a workspace whose credit balance is at or below zero gets HTTP 402 insufficient_quota before the model runs. It is not a soft quota warning — it is a hard stop, and topping up is the only fix. See API errors.

Migration checklist for an existing app

  1. Swap credentials. Replace the base URL and API key. Keep them in environment variables; SYNAPSEX_API_KEY is the conventional name.
  2. Replace the model id. Start with synapsex-forge-code-14b-v1. GET /models returns the SynapseX catalog but is not filtered to what your key may call, so an id from it can still be refused with a 403 that names the ids you can use — see Models.
  3. Remove unsupported parameters. Strip tools, response_format, seed, stop, n, logprobs and penalties from your request builder so the behaviour you expect is not silently missing.
  4. Add a 402 handler. Catch it distinctly from 429 and surface “out of credits” to whoever can top up, rather than retrying forever.
  5. Log X-SynapseX-Request-Id when a response carries it, so support requests are actionable. It is present on /chat/completions responses that reached the model gateway, and absent on requests rejected before that.
ModelsErrors