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.
For Python 3.10 or later.
Install#
pip install vaakiniThe 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)import asynciofrom vaakini import AsyncVaakiniasync 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_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.
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,taorte. 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) orwav.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.
falseturns 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.
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 charactersA 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.
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.
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 sentenceVaakini 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#
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.
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.
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| 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 APIErrors, with code, message, status_code (None on a stream() connection) and retryable. APITimeoutError is an APIConnectionError.