> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authentication, base URL, error handling, and OpenAI compatibility for the SynapsAI Cloud API

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](/manage/api-keys).

```bash theme={null}
export SYNAPSAI_API_KEY="your-api-key"
```

Include the key on every request:

```
Authorization: Bearer SYNAPSAI_API_KEY
```

<Warning>
  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.
</Warning>

### List models

Verify authentication and list deployed models:

```bash theme={null}
curl https://api.synapsai.cloud/v1/models \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY"
```

## Python SDK

Install the official Python client:

```bash theme={null}
pip install --upgrade synapsai-python
```

```python theme={null}
from synapsai import SynapsAI

client = SynapsAI()  # reads SYNAPSAI_API_KEY from the environment
```

See the [Inference quickstart](/guides/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:

```bash theme={null}
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](/guides/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](https://platform.synapsai.cloud/models). This is not the Hugging Face repository name.
* Successful responses return JSON. Streaming endpoints return Server-Sent Events (SSE). See [Streaming](/guides/streaming).

## Errors

Errors return a JSON object with an `error` field:

```json theme={null}
{
  "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](/support/troubleshooting).

## Rate limits

Default limits apply per account and per deployed model. See [Rate limits](/resources/rate-limits) for current defaults and how to request higher throughput.

## Debugging requests

1. Confirm the model is not **Building** or **Failed** — **Sleeping** and **Ready** deployments both accept inference requests.
2. Check the model **Logs** tab for deployment and runtime errors.
3. Verify your API key is scoped to the target model.
4. Compare your request against the [supported tasks](/resources/tasks) table and the endpoint reference below.