# The Python SDK

> vaakini: speech from text you have in full, speech from text as it is written, voices, custom voices and errors, for sync and asyncio code.

For Python 3.10 or later.

## Install

```shell
pip install vaakini
```

## The client

`Vaakini` for synchronous code, `AsyncVaakini` for asyncio: the same calls, awaited.

**Sync**

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

audio = client.speech.create(
    input="नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।",
    voice="Monika",
    language="hi",
    response_format="mp3",
)
with open("speech.mp3", "wb") as f:
    f.write(audio)
```

**Async**

```python
import asyncio

from vaakini import AsyncVaakini


async def main() -> None:
    async with AsyncVaakini() as client:
        audio = await client.speech.create(input="नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।", voice="Monika", language="hi")
    with open("speech.mp3", "wb") as f:
        f.write(audio)


asyncio.run(main())
```

- `api_key` (`string`, Default: $VAAKINI_API_KEY): Your Vaakini API key.
- `base_url` (`string`, Default https://api.vaakini.com): The API's URL.
- `timeout` (`number`, Default 60.0): Seconds to wait for a connection, and for each piece of a response.

Close a client with `client.close()` (`await client.close()`), or use it in a `with` (`async with`) statement.

## Speech

For a text you have in full.

`client.speech.create(...)` returns the audio as `bytes`, once all of it has arrived: the sample above.

### As it arrives

`client.speech.stream(...)` takes the same arguments and yields the audio in pieces while it is being spoken, so you can play the first sentence while the rest is made. With `AsyncVaakini`, iterate with `async for`.

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

# 16-bit mono PCM at 24000 Hz, written as it arrives.
with open("speech.pcm", "wb") as f:
    for chunk in client.speech.stream(
        input="नमस्ते, आपका ऑर्डर कल पहुँच जाएगा। डिलीवरी से पहले आपको कॉल आएगा।",
        voice="Monika",
        language="hi",
        response_format="pcm",
    ):
        f.write(chunk)
```

The request is sent when the iteration starts, which is also where its errors are raised. An `APIConnectionError` in the middle of the audio means the take failed: treat the request as failed.

### Arguments

- `input` (`string`, Required): The text, up to 20,000 characters.
- `voice` (`string`, Required): One of Vaakini’s voices by name, in any case (`Monika`), or the id of one of your org’s [custom voices](https://docs.vaakini.com/custom-voices.md) (`cv_…`). [Voices and languages](https://docs.vaakini.com/voices.md) lists them.
- `language` (`string`, Optional): The language the text is in: `as` , `bn` , `en` , `gu` , `hi` , `kn` , `ml` , `mr` , `or` , `pa` , `ta` or `te`. Left out, the model picks it from the script of each sentence.
- `response_format` (`string`, Default "mp3"): `mp3`, `pcm` (16-bit little-endian mono, 24000 Hz, no header) or `wav`.
- `model` (`string`, Default "vaakini-tts-1"): The model. This is the only one.
- `normalize` (`boolean`, Optional; None: on): Speak numbers, currency, dates, times, OTPs, phone numbers, URLs and emails as words in the request’s language. `false` turns it off: the text is spoken as written.
- `temperature` (`number`, Optional; None: the model's default): Sampling temperature, 0.1 to 1.5: lower is steadier, higher is more varied.
- `top_k` (`integer`, Optional; None: the model's default): Sample from the k likeliest codes, 1 to 2048.
- `top_p` (`number`, Optional; None: the model's default): Nucleus sampling, above 0 and at most 1.
- `repetition_penalty` (`number`, Optional; None: the model's default): Penalty on recently repeated codes, 0 to 5.

## Streamed text

For text that arrives as it is written, such as an LLM's reply.

`client.stream(...)` opens a connection: text goes in piece by piece, and each sentence’s audio comes back as soon as the sentence is complete.

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

# Your LLM's reply, as it writes it.
tokens = ["नमस्ते, आपका ", "ऑर्डर कल पहुँच ", "जाएगा। डिलीवरी से ", "पहले आपको कॉल आएगा।"]

with client.stream(voice="Monika", language="hi") as stream, open("reply.pcm", "wb") as f:
    for token in tokens:
        stream.send_text(token)
    stream.flush()

    for event in stream:
        if event.type == "sentence":
            print(event.index, event.text)
        elif event.type == "audio":
            f.write(event.data)  # 16-bit mono PCM, 24000 Hz
        elif event.type == "done":
            print(event.sentences, "sentences,", event.characters, "characters")
```

```text
0 नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।
1 डिलीवरी से पहले आपको कॉल आएगा।
2 sentences, 64 characters
```

A reply is one **segment**: `send_text()` any number of times, then `flush()`. Its events are a `SentenceEvent` before each sentence’s `AudioEvent`s, and a `DoneEvent` at the end, where the iteration stops. The next `send_text()` starts the next segment on the same connection; iterate again for its events.

`stream(...)` takes `voice`, `language`, `model` and the options that `speech.create()` takes, and `format`: `pcm` (the default) or `mp3`.

### While the text is still arriving

To play audio while the LLM is still writing, send on one task and iterate on another, once the segment’s first `send_text()` has been called. With the synchronous client, use two threads the same way.

```python
import asyncio

from vaakini import AsyncVaakini

TOKENS = ["नमस्ते, आपका ", "ऑर्डर कल पहुँच ", "जाएगा। डिलीवरी से ", "पहले आपको कॉल आएगा।"]


async def main() -> None:
    async with AsyncVaakini() as client, client.stream(voice="Monika", language="hi") as stream:
        await stream.send_text(TOKENS[0])

        async def send_rest() -> None:
            for token in TOKENS[1:]:
                await stream.send_text(token)
            await stream.flush()

        sender = asyncio.create_task(send_rest())
        audio = bytearray()
        async for event in stream:
            if event.type == "audio":
                audio += event.data  # play it here, as it arrives
            elif event.type == "done":
                print(event.sentences, "sentences,", len(audio) / 48000, "seconds")
        await sender


asyncio.run(main())
```

### Interruptions

`stream.cancel()` ends a segment early, for a barge-in: its remaining audio is dropped, and its iteration stops at a `CancelledEvent`, which counts the sentences sent in full before the cancel. The next segment’s text can be sent at once.

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

with client.stream(voice="Monika", language="hi") as stream:
    stream.send_text("पहला वाक्य यहाँ है। दूसरा वाक्य भी बोला जाएगा। तीसरा वाक्य शायद नहीं बोला जाएगा।")
    stream.flush()
    for event in stream:
        if event.type == "sentence" and event.index == 1:
            stream.cancel()  # the caller spoke over the reply
        elif event.type == "cancelled":
            print("cancelled after", event.sentences, "sentence")

    # The same connection speaks the next reply.
    stream.send_text("जी, बताइए।")
    stream.flush()
    for event in stream:
        if event.type == "done":
            print("spoke", event.sentences, "sentence")
```

```text
cancelled after 1 sentence
spoke 1 sentence
```

Vaakini closes a connection that sends nothing for 30 minutes, and when one of its servers restarts. A closed connection raises `APIConnectionError`: open a new one.

## Voices and models

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

for voice in client.voices.list():
    print(voice.id, voice.category, voice.gender, voice.languages)

model = client.models.list()[0]
print(model.id, model.languages, model.formats)
```

`voices.list()` is Vaakini’s voices, then your org’s custom voices: each has `id`, `name`, `category` (`builtin` or `cloned`), `gender`, `description` and `languages`. [Voices and languages](https://docs.vaakini.com/voices.md) has more.

## Custom voices

Your org’s own voices, each made from one recording. [Custom voices](https://docs.vaakini.com/custom-voices.md) is the guide.

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

voice = client.custom_voices.create(
    name="Priya (support)",
    audio="priya.wav",  # a path, bytes or an open binary file
    transcript="नमस्ते, मैं प्रिया बोल रही हूँ।",
    language="hi",
    gender="female",
)
print(voice.id, voice.revision)

print(client.custom_voices.list().voices)
print(client.custom_voices.get(voice.id).name)

voice = client.custom_voices.update(voice.id, name="Priya")
voice = client.custom_voices.replace_recording(
    voice.id,
    audio="priya2.wav",
    transcript="नमस्ते, मैं प्रिया बोल रही हूँ।",
    language="hi",
)
print(voice.name, voice.revision)

client.custom_voices.delete(voice.id)
```

`list()` returns `.enabled`, `.limit` and `.voices`. `update()` changes the name, the gender or both; a `gender` of `None` clears it. `create()` and `replace_recording()` also take `mode`.

## Errors

Every error the SDK raises is a `vaakini.VaakiniError`.

```python
import vaakini
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

try:
    client.speech.create(input="नमस्ते।", voice="NoSuchVoice")
except vaakini.APIError as e:
    print(type(e).__name__, e.code, e.status_code, e.retryable)
    print(e.message)
except vaakini.APIConnectionError:
    print("the API could not be reached, or the audio ended early")
```

```text
BadRequestError bad_request 400 False
invalid request: voice: Input should be one of the voices GET /v1/voices lists
```

| Error | code |  |
| --- | --- | --- |
| BadRequestError | `bad_request` | The request is invalid; the message names the field. |
| AuthenticationError | `unauthorized` | The API key is missing or invalid. |
| InsufficientCreditsError | `insufficient_credits` | The org is out of credit. |
| NotFoundError | `not_found` | No such custom voice in your org. |
| CustomVoicesNotEnabledError | `custom_voices_not_enabled` | Custom voices aren't enabled for your org. |
| CustomVoiceLimitError | `custom_voice_limit` | Your org holds as many custom voices as it can. |
| RateLimitError | `rate_limited` | The model is at capacity; try again. |
| UnavailableError | `unavailable` | The model is unavailable; try again. |
| ModelTimeoutError | `timeout` | The model sent no audio in time; try again. |
| InternalServerError | `internal` | The request failed on Vaakini's side; try again. |
| APIConnectionError |  | The API could not be reached, or the connection ended early. |
| APITimeoutError |  | The API did not answer within the client’s `timeout`. |

The first ten are `APIError`s, with `code`, `message`, `status_code` (`None` on a `stream()` connection) and `retryable`. `APITimeoutError` is an `APIConnectionError`.
