Vaakini docs

Reference

API reference

Every HTTP endpoint with its fields and responses, from the API's OpenAPI document.

View as Markdown

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"Required
inputstring, min length 1, max length 20000Required
The text to speak.
voicestring, min length 1Required
A voice GET /v1/voices lists: 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) or wav.
sample_rate24000
stream_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.
Example
{  "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 voice takes 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 100Required
    gender"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[]Required
    revisioninteger, ≥ 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 voice takes 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 100Required
    gender"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[]Required
    revisioninteger, ≥ 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 100
gender"female" | "male" | null
Null clears it.

Responses

  • 200Successful Response

    idstringRequired
    What voice takes 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 100Required
    gender"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[]Required
    revisioninteger, ≥ 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 voice takes 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 100Required
    gender"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[]Required
    revisioninteger, ≥ 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