Vaakini docs

API

The HTTP API

POST /v1/audio/speech: send a text, get its audio back as it is spoken. From any language.

View as Markdown

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.mp3

The 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.

modelstringRequired
vaakini-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, ta or te. Left out, the model picks it from the script of each sentence.
response_formatstringDefault "mp3"
mp3, pcm or wav.
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. false turns 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_formatContent-TypeThe audio
mp3audio/mpegMP3, 24000 Hz, mono
pcmaudio/pcm16-bit little-endian PCM, 24000 Hz, mono, no header
wavaudio/wavThe 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.

Shell
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.

Shell
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.

Shell
curl https://api.vaakini.com/v1/models

GET /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.