# SDKs & compatibility

The Svara Python SDK, and using the OpenAI or ElevenLabs SDKs against Svara.

## Svara Python SDK

The official SDK. One dependency-light package (`httpx` + `websockets`) that covers the whole surface: sync and async clients, HTTP streaming, the [input-streaming WebSocket](https://docs.kenpathlabs.com/input-streaming.md) behind one method call, pronunciation dictionaries, a CLI, and drop-in [LiveKit](https://docs.kenpathlabs.com/livekit.md) / [Pipecat](https://docs.kenpathlabs.com/pipecat.md) plugins. The distribution is `svara-voice`; the import is `import svara`.

```bash
pip install git+https://github.com/kenpath-labs/svara-python.git
```

```python
from svara import Svara

client = Svara()                          # reads SVARA_API_KEY
audio = client.speech.create(
    input="नमस्ते! Welcome to Svara.",
    voice="sv_enhdbrj5",                  # Aanya
    response_format="mp3",
)
open("hello.mp3", "wb").write(audio)

# low latency: stream chunks as they generate
for chunk in client.speech.stream(input="...", voice="sv_enhdbrj5",
                                  response_format="pcm"):
    player.feed(chunk)
```

```python
from svara import AsyncSvara

client = AsyncSvara()

# the endpoint voice agents should be on: feed an LLM token stream,
# audio starts before the sentence ends (one WebSocket, not N requests)
async for audio in client.speech.stream_input(llm_deltas(), voice="sv_enhdbrj5"):
    player.feed(audio)
```

```
svara say "नमस्ते दुनिया" --voice sv_enhdbrj5 --out hello.mp3
svara voices --language hi
```

> The SDK installs from the repository until the first PyPI release lands; after that, `pip install svara-voice` is the same package and the same import. Extras use the same URL: `pip install "svara-voice[livekit] @ git+https://github.com/kenpath-labs/svara-python.git"`.

## OpenAI SDKs

The official OpenAI Python and JavaScript SDKs work against Svara unmodified: point `base_url` at Svara and pass your key. Svara-specific fields ride in `extra_body` (Python) or as extra properties (JS).

```bash
pip install openai
```

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.kenpathlabs.com/v1", api_key=SVARA_API_KEY)
audio = client.audio.speech.create(
    model="svara-1",
    voice="sv_enhdbrj5",  # Aanya
    input="Namaste!",
    response_format="mp3",
    extra_body={"lang": "hindi", "stream": False},   # svara extensions
)
audio.write_to_file("out.mp3")
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.kenpathlabs.com/v1", apiKey: SVARA_API_KEY });
const res = await client.audio.speech.create({
  model: "svara-1",
  voice: "sv_enhdbrj5", // Aanya
  input: "Namaste!",
  response_format: "mp3",
  // @ts-expect-error - svara extension
  lang: "hindi",
});
```

## ElevenLabs SDKs

The official ElevenLabs SDKs also work unmodified, including their realtime WebSocket client. Pass any non-empty `api_key`; its presence is also how `GET /v1/models` decides to answer in the ElevenLabs array shape.

```bash
pip install elevenlabs
```

```python
from elevenlabs.client import ElevenLabs

client = ElevenLabs(base_url="https://api.kenpathlabs.com", api_key=SVARA_API_KEY)
audio = client.text_to_speech.convert(
    voice_id="sv_enhdbrj5",  # Aanya
    text="Namaste!",
    model_id="eleven_multilingual_v2",   # accepted, ignored
    output_format="mp3_44100_128",
)
```

```javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ baseUrl: "https://api.kenpathlabs.com", apiKey: SVARA_API_KEY });
const stream = await client.textToSpeech.stream("sv_enhdbrj5", { text: "Namaste!" }); // voice: Aanya
```

## Base URL conventions

> Mind the `/v1`: **OpenAI SDKs include it** in the base URL (`https://api.kenpathlabs.com/v1`), while **ElevenLabs SDKs do not** (`https://api.kenpathlabs.com`); they append `v1/…` themselves.

## Compatibility surface

What maps, and what to expect:

- **Full support**: TTS + streaming, all output formats and rates, timestamps, the realtime WebSocket, voice list/search, models, languages.
- **Honored**: `voice_settings.speed` maps onto the native speed parameter (their 0.7–1.2 range sits inside our 0.7–1.5) — on HTTP, with-timestamps and the realtime WebSocket alike.
- **Accepted and ignored**: `voice_settings` (stability/similarity/style), `seed`, `model_id`, `previous_text`/`next_text`, request stitching. These don’t map onto this model; requests including them still succeed. (Pronunciation dictionaries _are_ supported — see [the guide](https://docs.kenpathlabs.com/pronunciation.md).)
- **Stubbed**: user/subscription and voice-settings endpoints return valid, permissive shapes so SDK flows don’t break.

A machine-readable OpenAPI document is served live at `https://api.kenpathlabs.com/openapi.json`: generate typed clients from it (Fern, Stainless, Scalar) for languages the official SDK doesn’t cover yet.