API overview

The SynapsAI Cloud API lets you run inference against your deployed models over HTTPS. Most LLM and embeddings endpoints follow the OpenAI API format, so you can often switch providers by changing the base URL and API key.

Base URL

All API requests use:

https://api.synapsai.cloud

Versioned endpoints are prefixed with /v1 (for example, /v1/chat/completions).

Authentication

The API uses Bearer token authentication with your API key.

export SYNAPSAI_API_KEY="your-api-key"

Include the key on every request:

Authorization: Bearer SYNAPSAI_API_KEY

Keep API keys secret. Never embed them in client-side code, public repositories, or browser bundles. Load keys from environment variables or a secret manager on the server.

List models

Verify authentication and list deployed models:

curl https://api.synapsai.cloud/v1/models \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY"

Python SDK

Install the official Python client:

pip install --upgrade synapsai-python

from synapsai import SynapsAI

client = SynapsAI()  # reads SYNAPSAI_API_KEY from the environment

See the Inference quickstart for a full walkthrough.

OpenAI compatibility

SynapsAI Cloud implements OpenAI-compatible endpoints for common workflows:

Capability	Endpoint	Notes
Chat completions	`POST /v1/chat/completions`	Supports streaming, tools, and tool choice
Completions	`POST /v1/completions`	For encoder-decoder and legacy models
Embeddings	`POST /v1/embeddings`	Same request shape as OpenAI
Images	`POST /v1/images/generations`, `/v1/images/edits`	Image generation and editing
Audio	`POST /v1/audio/speech`, `/v1/audio/transcriptions`	Text-to-speech and speech-to-text

To use OpenAI-compatible libraries, set:

export OPENAI_API_BASE="https://api.synapsai.cloud/v1"
export OPENAI_API_KEY="$SYNAPSAI_API_KEY"

For a full migration walkthrough, see Migrate from OpenAI.

Request and response format

Send JSON bodies with Content-Type: application/json unless the endpoint accepts multipart uploads (for example, audio transcription).
Replace model in each request with your model ID from the dashboard. This is not the Hugging Face repository name.
Successful responses return JSON. Streaming endpoints return Server-Sent Events (SSE). See Streaming.

Errors

Errors return a JSON object with an error field:

{
  "error": {
    "message": "Invalid or restricted API key.",
    "type": "InvalidAPIKeyError",
    "code": null
  }
}

HTTP status	Meaning
`400`	Invalid request parameters or payload
`401`	Missing or invalid API key
`403`	Key lacks permission for the model
`404`	Model or resource not found
`429`	Rate limit exceeded
`500`	Internal server error

For a catalog of error types and fixes, see Troubleshooting.

Rate limits

Default limits apply per account and per deployed model. See Rate limits for current defaults and how to request higher throughput.

Debugging requests

Confirm the model is not Building or Failed — Sleeping and Ready deployments both accept inference requests.
Check the model Logs tab for deployment and runtime errors.
Verify your API key is scoped to the target model.
Compare your request against the supported tasks table and the endpoint reference below.

Overview

Endpoints

Base URL

Authentication

List models

Python SDK

OpenAI compatibility

Request and response format

Errors

Rate limits

Debugging requests

​Base URL

​Authentication

​List models

​Python SDK

​OpenAI compatibility

​Request and response format

​Errors

​Rate limits

​Debugging requests

Base URL

Authentication

List models

Python SDK

OpenAI compatibility

Request and response format

Errors

Rate limits

Debugging requests