API
The HTTP API
POST /v1/audio/speech: send a text, get its audio back as it is spoken. From any language.
Authentication#
Every request carries an API key from the dashboard’s API keys page.
Authorization: Bearer vk_…The host is https://api.vaakini.com. A missing or wrong key is answered with 401 (unauthorized).
The request#
POST /v1/audio/speech with a JSON body: the text, a voice and the model.
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": "Monika", "language": "hi", "input": "नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।", "response_format": "mp3"}' \ --output speech.mp3curl https://api.vaakini.com/v1/audio/speech \ -H "Authorization: Bearer $VAAKINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "vaakini-tts-1", "voice": "Monika", "language": "hi", "input": "नमस्ते, आपका ऑर्डर कल पहुँच जाएगा। डिलीवरी से पहले आपको कॉल आएगा।", "response_format": "pcm", "temperature": 0.6 }' \ --output speech.pcmThe text is split into sentences and each is spoken in turn. The request is shaped like OpenAI’s /v1/audio/speech, so a client written for that needs a new URL, key, model and voice.
Fields#
Any other field is refused.
modelstringRequiredvaakini-tts-1.inputstringRequired- The text to speak, 1 to 20,000 characters. It can carry emotion tags.
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,pcmorwav.sample_rateintegerDefault 24000- 24000 is the only rate.
normalizebooleanOptional; left out or null: 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; left out or null: the model's default- Sampling temperature, 0.1 to 1.5: lower is steadier, higher is more varied.
top_kintegerOptional; left out or null: the model's default- Sample from the k likeliest codes, 1 to 2048.
top_pnumberOptional; left out or null: the model's default- Nucleus sampling, above 0 and at most 1.
repetition_penaltynumberOptional; left out or null: the model's default- Penalty on recently repeated codes, 0 to 5.
The response#
The audio, streamed as it is spoken.
| response_format | Content-Type | The audio |
|---|---|---|
| mp3 | audio/mpeg | MP3, 24000 Hz, mono |
| pcm | audio/pcm | 16-bit little-endian PCM, 24000 Hz, mono, no header |
| wav | audio/wav | The same PCM with a WAV header |
The body is chunked: the first audio arrives when the first sentence starts to be spoken, and the response ends when the last one has been. Read it as a stream to play it while it arrives. Because a WAV’s header is sent before its length is known, some players show no duration for it.
Errors#
A JSON body with the error's code, a message and whether trying again can help.
curl -i https://api.vaakini.com/v1/audio/speech \ -H "Authorization: Bearer $VAAKINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "vaakini-tts-1", "voice": "Monika", "input": "नमस्ते।", "speed": 1.2}'HTTP/1.1 400 Bad Requestcontent-type: application/json{"error":{"code":"bad_request","message":"invalid request: speed: vaakini-tts-1 takes no speed","retryable":false}}Errors lists every code and its status.
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 your HTTP client raises as an error (an incomplete or prematurely closed response). Treat that request as failed.
Voices and the model#
Two GETs say what voice and model take.
curl https://api.vaakini.com/v1/voices \ -H "Authorization: Bearer $VAAKINI_API_KEY"GET /v1/voices lists the voices your org can speak with; Listing voices shows its answer.
curl https://api.vaakini.com/v1/modelsGET /v1/models needs no key. It answers the model with its voices’ names, languages, formats, sample rates and options. The API reference has every field of both.