Vaakini docs

Clients

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.

View as Markdown

For Python 3.10 or later.

Install#

pip install vaakini

The client#

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

from vaakini import Vaakiniclient = Vaakini()  # reads VAAKINI_API_KEYaudio = client.speech.create(    input="नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।",    voice="Monika",    language="hi",    response_format="mp3",)with open("speech.mp3", "wb") as f:    f.write(audio)
api_keystringDefault: $VAAKINI_API_KEY
Your Vaakini API key.
base_urlstringDefault https://api.vaakini.com
The API's URL.
timeoutnumberDefault 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 Vaakiniclient = 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#

inputstringRequired
The text, up to 20,000 characters.
voicestringRequired
One of Vaakini’s voices by name, in any case (Monika), or the id of one of your org’s custom voices (cv_…). Voices and languages lists them.
languagestringOptional
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_formatstringDefault "mp3"
mp3, pcm (16-bit little-endian mono, 24000 Hz, no header) or wav.
modelstringDefault "vaakini-tts-1"
The model. This is the only one.
normalizebooleanOptional; 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.
temperaturenumberOptional; None: the model's default
Sampling temperature, 0.1 to 1.5: lower is steadier, higher is more varied.
top_kintegerOptional; None: the model's default
Sample from the k likeliest codes, 1 to 2048.
top_pnumberOptional; None: the model's default
Nucleus sampling, above 0 and at most 1.
repetition_penaltynumberOptional; 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 Vaakiniclient = 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")
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 AudioEvents, 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 asynciofrom vaakini import AsyncVaakiniTOKENS = ["नमस्ते, आपका ", "ऑर्डर कल पहुँच ", "जाएगा। डिलीवरी से ", "पहले आपको कॉल आएगा।"]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 senderasyncio.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 Vaakiniclient = Vaakini()  # reads VAAKINI_API_KEYwith 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")
cancelled after 1 sentencespoke 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 Vaakiniclient = Vaakini()  # reads VAAKINI_API_KEYfor 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 has more.

Custom voices#

Your org’s own voices, each made from one recording. Custom voices is the guide.

Python
from vaakini import Vaakiniclient = Vaakini()  # reads VAAKINI_API_KEYvoice = 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 vaakinifrom vaakini import Vaakiniclient = Vaakini()  # reads VAAKINI_API_KEYtry:    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")
BadRequestError bad_request 400 Falseinvalid request: voice: Input should be one of the voices GET /v1/voices lists
Errorcode
BadRequestErrorbad_requestThe request is invalid; the message names the field.
AuthenticationErrorunauthorizedThe API key is missing or invalid.
InsufficientCreditsErrorinsufficient_creditsThe org is out of credit.
NotFoundErrornot_foundNo such custom voice in your org.
CustomVoicesNotEnabledErrorcustom_voices_not_enabledCustom voices aren't enabled for your org.
CustomVoiceLimitErrorcustom_voice_limitYour org holds as many custom voices as it can.
RateLimitErrorrate_limitedThe model is at capacity; try again.
UnavailableErrorunavailableThe model is unavailable; try again.
ModelTimeoutErrortimeoutThe model sent no audio in time; try again.
InternalServerErrorinternalThe request failed on Vaakini's side; try again.
APIConnectionErrorThe API could not be reached, or the connection ended early.
APITimeoutErrorThe API did not answer within the client’s timeout.

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