Reference
API reference
Every HTTP endpoint with its fields and responses, from the API's OpenAPI document.
Speech#
A text in, its audio out. The guide is The HTTP API.
post/v1/audio/speechCreate speech
POST https://api.vaakini.com/v1/audio/speech
Synthesizes input and streams the audio back as it is made. The input is split into sentences and each is synthesized in turn, so the first audio arrives after the first sentence.
The status is sent with the first audio, so an error after audio has started can only abort the body: the response ends without its final chunk, which HTTP clients raise as an error. Treat it as a failed request.
Request body
model"vaakini-tts-1"Requiredinputstring, min length 1, max length 20000Required- The text to speak.
voicestring, min length 1Required- A voice
GET /v1/voiceslists: a built-in voice's name, in any case (e.g.Monika), or one of your org's custom voices (cv_…). language"as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" | null- The text's language. Left out or null: the model picks it from the text's script.
response_format"mp3" | "pcm" | "wav"mp3,pcm(16-bit little-endian mono) orwav.sample_rate24000stream_format"audio"normalizeboolean | null- Speak numbers, currency, dates, times, OTPs, phone numbers, URLs and emails as words in the request's language. Left out or null: the model's default (on).
temperaturenumber | null, ≥ 0.1, ≤ 1.5- Sampling temperature: lower is steadier, higher is more varied. Left out or null: the model's default.
top_kinteger | null, ≥ 1, ≤ 2048- Sample from the k likeliest codes. Left out or null: the model's default.
top_pnumber | null, ≤ 1- Nucleus sampling, above 0 and at most 1. Left out or null: the model's default.
repetition_penaltynumber | null, ≥ 0, ≤ 5- Penalty on recently repeated codes. Left out or null: the model's default.
{ "model": "vaakini-tts-1", "input": "नमस्ते, आप कैसे हैं?", "voice": "Monika", "language": "hi", "response_format": "mp3"}Responses
200The audio, streamed.
400Invalid request (`bad_request`)
401Missing or invalid API key (`unauthorized`)
402The org is out of credit (`insufficient_credits`): buy credit in the dashboard
429The model is at capacity (`rate_limited`): try again
500The request failed on our side (`internal`)
502The model is unavailable (`unavailable`): try again
504The model sent no audio in time (`timeout`): try again
Voices and models#
What voice and model take. The guide is Voices and languages.
get/v1/voicesList voices
GET https://api.vaakini.com/v1/voices
The voices your org can speak with: the built-in voices, then your org's custom voices. Takes no query parameters.
Responses
200Successful Response
voicesVoice[]Required
400A query parameter was sent (`bad_request`)
401Missing or invalid API key (`unauthorized`)
402The org is out of credit (`insufficient_credits`)
get/v1/modelsList models
GET https://api.vaakini.com/v1/models
The model, with its built-in voices, languages, formats, sample rates and options. Needs no API key.
Responses
200Successful Response
modelsModel[]Required
Custom voices#
Your org’s own voices, enabled per org on request. The guide is Custom voices.
get/v1/custom-voicesList your custom voices
GET https://api.vaakini.com/v1/custom-voices
Your org's custom voices, oldest first, whether they're enabled for it, and how many it can hold.
Responses
200Successful Response
enabledbooleanRequired- Whether custom voices are enabled for your org. Until they are, creating one is refused (
custom_voices_not_enabled); write to [email protected] to get them enabled. limitintegerRequired- How many custom voices your org can hold.
voicesCustomVoice[]Required
401Missing or invalid API key (`unauthorized`)
post/v1/custom-voicesCreate a custom voice
POST https://api.vaakini.com/v1/custom-voices
Creates a custom voice from one reference recording. Your org alone can speak it, with its id as voice, a few seconds after this returns: until then a request that names it is refused as an unknown voice. Creating and keeping voices is free; speaking one costs what any voice costs.
Responses
201Created: ready to speak
idstringRequired- What
voicetakes on/v1/stream,/v1/audio/speech, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it. namestring, min length 1, max length 100Requiredgender"female" | "male" | nullRequired- Your label for the voice, shown in
GET /v1/voices; null when you set none. It doesn't change how the voice sounds. language"as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te"Required- The recording's language. The voice speaks every language the model does.
modelsCustomVoiceModel[]Requiredrevisioninteger, ≥ 1Required- Which recording the voice speaks: 1 when created, one more each time its recording is replaced (
PUT /v1/custom-voices/{voice_id}/recording). created_atstring (date-time)Required
Example { "id": "cv_t76u7a3um3xayk4b", "name": "Priya (support)", "gender": "female", "language": "hi", "models": [ { "model": "vaakini-tts-1", "mode": "icl_spk" } ], "revision": 1, "created_at": "2026-11-10T01:52:33Z"}401Missing or invalid API key (`unauthorized`)
403Custom voices aren't enabled for your org (`custom_voices_not_enabled`)
409Your org holds as many custom voices as it can (`custom_voice_limit`)
422The request failed validation, or the recording couldn't be used (`bad_request`, naming the field)
503The model or the voice store is unavailable (`unavailable`); nothing was kept, try again
get/v1/custom-voices/{voice_id}Get a custom voice
GET https://api.vaakini.com/v1/custom-voices/{voice_id}
Parameters
voice_idpath, stringRequired
Responses
200Successful Response
idstringRequired- What
voicetakes on/v1/stream,/v1/audio/speech, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it. namestring, min length 1, max length 100Requiredgender"female" | "male" | nullRequired- Your label for the voice, shown in
GET /v1/voices; null when you set none. It doesn't change how the voice sounds. language"as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te"Required- The recording's language. The voice speaks every language the model does.
modelsCustomVoiceModel[]Requiredrevisioninteger, ≥ 1Required- Which recording the voice speaks: 1 when created, one more each time its recording is replaced (
PUT /v1/custom-voices/{voice_id}/recording). created_atstring (date-time)Required
Example { "id": "cv_t76u7a3um3xayk4b", "name": "Priya (support)", "gender": "female", "language": "hi", "models": [ { "model": "vaakini-tts-1", "mode": "icl_spk" } ], "revision": 1, "created_at": "2026-11-10T01:52:33Z"}401Missing or invalid API key (`unauthorized`)
403Custom voices aren't enabled for your org (`custom_voices_not_enabled`)
404No such custom voice in your org
patch/v1/custom-voices/{voice_id}Update a custom voice
PATCH https://api.vaakini.com/v1/custom-voices/{voice_id}
Only the name and gender change here. A gender of null clears it. To change the recording, transcript, language or mode, replace the recording (PUT …/recording).
Parameters
voice_idpath, stringRequired
Request body
namestring, min length 1, max length 100gender"female" | "male" | null- Null clears it.
Responses
200Successful Response
idstringRequired- What
voicetakes on/v1/stream,/v1/audio/speech, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it. namestring, min length 1, max length 100Requiredgender"female" | "male" | nullRequired- Your label for the voice, shown in
GET /v1/voices; null when you set none. It doesn't change how the voice sounds. language"as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te"Required- The recording's language. The voice speaks every language the model does.
modelsCustomVoiceModel[]Requiredrevisioninteger, ≥ 1Required- Which recording the voice speaks: 1 when created, one more each time its recording is replaced (
PUT /v1/custom-voices/{voice_id}/recording). created_atstring (date-time)Required
Example { "id": "cv_t76u7a3um3xayk4b", "name": "Priya (support)", "gender": "female", "language": "hi", "models": [ { "model": "vaakini-tts-1", "mode": "icl_spk" } ], "revision": 1, "created_at": "2026-11-10T01:52:33Z"}401Missing or invalid API key (`unauthorized`)
403Custom voices aren't enabled for your org (`custom_voices_not_enabled`)
404No such custom voice in your org
422The request failed validation
delete/v1/custom-voices/{voice_id}Delete a custom voice
DELETE https://api.vaakini.com/v1/custom-voices/{voice_id}
Deletes the voice at once: requests naming it are refused from then on, and its recording and transcript are deleted.
Parameters
voice_idpath, stringRequired
Responses
204Deleted
401Missing or invalid API key (`unauthorized`)
403Custom voices aren't enabled for your org (`custom_voices_not_enabled`)
404No such custom voice in your org
put/v1/custom-voices/{voice_id}/recordingReplace a custom voice's recording
PUT https://api.vaakini.com/v1/custom-voices/{voice_id}/recording
Replaces the voice's recording, transcript, language and mode together, under the same id: every request from then on speaks the new recording (within a few seconds), and a reply already being spoken finishes in the old one. The voice's revision goes up by one. The name and gender don't change. If the new recording can't be used, the voice keeps its old one.
Parameters
voice_idpath, stringRequired
Responses
200Replaced: the new recording is ready to speak
idstringRequired- What
voicetakes on/v1/stream,/v1/audio/speech, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it. namestring, min length 1, max length 100Requiredgender"female" | "male" | nullRequired- Your label for the voice, shown in
GET /v1/voices; null when you set none. It doesn't change how the voice sounds. language"as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te"Required- The recording's language. The voice speaks every language the model does.
modelsCustomVoiceModel[]Requiredrevisioninteger, ≥ 1Required- Which recording the voice speaks: 1 when created, one more each time its recording is replaced (
PUT /v1/custom-voices/{voice_id}/recording). created_atstring (date-time)Required
Example { "id": "cv_t76u7a3um3xayk4b", "name": "Priya (support)", "gender": "female", "language": "hi", "models": [ { "model": "vaakini-tts-1", "mode": "icl_spk" } ], "revision": 1, "created_at": "2026-11-10T01:52:33Z"}401Missing or invalid API key (`unauthorized`)
403Custom voices aren't enabled for your org (`custom_voices_not_enabled`)
404No such custom voice in your org
422The request failed validation, or the recording couldn't be used (`bad_request`, naming the field)
503The model or the voice store is unavailable (`unavailable`); the voice keeps its old recording, try again
OpenAPI document#
The whole HTTP API as OpenAPI 3.1, for code generators and API clients. The WebSocket has its own page.
curl https://api.vaakini.com/openapi.json