Vaakini docs

Voices and options

Custom voices

Your org's own voices, each made from one short recording: create, list, rename, replace the recording, delete.

View as Markdown

Getting them enabled#

A custom voice is a voice of your org's own, made from one short recording of a speaker. Only your org can speak it.

Custom voices are switched on per org, on request: write to [email protected]. Until then, creating one is refused with custom_voices_not_enabled (HTTP 403); listing works, and says enabled: false.

Once enabled, make and manage voices on the dashboard’s Voices page, or with the API below. An org can hold 10. They are free to create and keep, and are spoken at the same price as every other voice.

The recording#

One speaker, clean speech, with the exact words that are spoken.

What it takes
FormatWAV, FLAC or Ogg
Length0.5 to 30 seconds; 3 to 10 seconds of clean speech works best. A longer one is refused, never trimmed.
TranscriptThe exact words spoken in the recording, up to 2,000 characters
LanguageThe recording's language, one of the twelve. The voice then speaks all twelve.

Create a voice#

POST /v1/custom-voices, as a multipart form.

Shell
curl https://api.vaakini.com/v1/custom-voices \  -H "Authorization: Bearer $VAAKINI_API_KEY" \  -F name="Priya (support)" \  -F gender=female \  -F language=hi \  -F transcript="नमस्ते, मैं प्रिया बोल रही हूँ।" \  -F [email protected]
namestringRequired
Your name for the voice, 1 to 100 characters.
audiofileRequired
The recording.
transcriptstringRequired
The exact words spoken in it.
languagestringRequired
The recording’s language: as, bn, en, gu, hi, kn, ml, mr, or, pa, ta or te.
genderstringOptional
female or male: your label for the voice, shown in GET /v1/voices. It doesn’t change how the voice sounds.
modelsJSON stringOptional
How the voice is cloned, e.g. {"vaakini-tts-1": {"mode": "icl"}}. The modes are icl_spk (the default, recommended), icl and spk.

The answer is the voice, with status 201:

{  "id": "cv_t76u7a3um3xayk4b",  "name": "Priya (support)",  "gender": "female",  "language": "hi",  "models": [{"model": "vaakini-tts-1", "mode": "icl_spk"}],  "revision": 1,  "created_at": "2026-11-16T09:30:12Z"}

Speak it#

Its id is what voice takes, in every client.

curl https://api.vaakini.com/v1/audio/speech \  -H "Authorization: Bearer $VAAKINI_API_KEY" \  -H "Content-Type: application/json" \  -d '{"model": "vaakini-tts-1", "voice": "cv_t76u7a3um3xayk4b", "language": "hi", "input": "आपका स्वागत है।"}' \  --output welcome.mp3

In the LiveKit plugin it is vaakini.TTS(voice="cv_…"), in the Pipecat service Settings(voice="cv_…"). The voice is also in your org’s GET /v1/voices, with category cloned.

List, rename, delete#

Shell
curl https://api.vaakini.com/v1/custom-voices \  -H "Authorization: Bearer $VAAKINI_API_KEY"
{  "enabled": true,  "limit": 10,  "voices": [    {      "id": "cv_t76u7a3um3xayk4b",      "name": "Priya (support)",      "gender": "female",      "language": "hi",      "models": [{"model": "vaakini-tts-1", "mode": "icl_spk"}],      "revision": 1,      "created_at": "2026-11-16T09:30:12Z"    }  ]}

enabled says whether custom voices are switched on for your org, and limit how many it can hold. GET /v1/custom-voices/{id} answers one voice.

PATCH changes the name, the gender or both, and nothing else; a gender of null clears it.

Shell
curl -X PATCH https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b \  -H "Authorization: Bearer $VAAKINI_API_KEY" \  -H "Content-Type: application/json" \  -d '{"name": "Priya", "gender": null}'

DELETE removes the voice at once, with its recording and transcript: requests that name it are refused from then on. It answers 204.

Shell
curl -X DELETE https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b \  -H "Authorization: Bearer $VAAKINI_API_KEY"

Replace the recording#

A better recording under the same id, so nothing that names the voice has to change.

Shell
curl -X PUT https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b/recording \  -H "Authorization: Bearer $VAAKINI_API_KEY" \  -F language=hi \  -F transcript="नमस्ते, मैं प्रिया बोल रही हूँ।" \  -F [email protected]

PUT /v1/custom-voices/{id}/recording takes audio, transcript, language and optionally models, as create does: the four change together. The voice’s revision goes up by one; its name and gender stay. Requests from then on speak the new recording, within a few seconds, and a reply already being spoken finishes in the old one. If the new recording can’t be used, the voice keeps its old one.

The Python SDK does all of this too:

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)

Errors#

codeStatusMeaning
custom_voices_not_enabled403Custom voices aren't enabled for your org.
custom_voice_limit409Your org holds as many custom voices as it can.
bad_request422A field is missing or wrong, or the recording can't be used; the message says which.
not_found404No such custom voice in your org.
unavailable503The voice couldn't be made just now. Nothing was kept: try again.

They come in the shape every error has.