DotVoice TTS Developers

API reference & integration guide

Base URL https://tts.dotvoice.in/api/v1 · JSON in, audio or JSON out · TLS only. Billed per character you send, from your prepaid wallet (₹0.5000 per 1,000 characters by default).

Authentication

Create a key in your account → API keys. Send it on every request:

Authorization: Bearer dv_live_…        (or)        X-API-Key: dv_live_…

Keys are shown once and stored only as a hash. Keep them on your server. Revoke a key in the portal and it stops working immediately.

Three ways to integrate

StyleEndpointUse it when
RESTPOST /tts/synthesizeYou want a complete file — IVR prompts, downloads, batch jobs.
HTTP streamingPOST /tts/streamStart playback while audio is generated; one utterance per request.
WebSocketwss /tts/wsLive calls and voice agents: many utterances on one connection, lowest latency, cancel any time (barge-in).

REST — a complete file

curl https://tts.dotvoice.in/api/v1/tts/synthesize \
  -H "Authorization: Bearer $DOTVOICE_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Your EMI of ₹2,500 is due tomorrow.", "voice_id": "dv_en_in_female_01",
       "language": "en-IN", "output_format": "wav", "sample_rate": 16000, "request_id": "order-1234"}' \
  -D - -o reminder.wav

The body is the audio. Headers: X-Request-Id, X-DotVoice-Chars-Billed, X-DotVoice-Cost, X-DotVoice-Balance (rupees, 6 decimals), plus X-Duration-Ms and X-Cache-Status.

HTTP streaming

curl -N https://tts.dotvoice.in/api/v1/tts/stream \
  -H "Authorization: Bearer $DOTVOICE_KEY" -H "Content-Type: application/json" \
  -d '{"text": "नमस्ते, आपका payment pending है।", "voice_id": "dv_hi_female_01",
       "language": "mixed-hi-en", "output_format": "ulaw", "sample_rate": 8000}' > reply.ulaw

Chunked raw audio (pcm_s16le, ulaw or alaw) as it is produced. The charge is made when the request is accepted, so the billing headers arrive with the first byte. Cancel with POST /tts/requests/{request_id}/cancel.

WebSocket — live calls and voice agents

Connect to wss://tts.dotvoice.in/api/v1/tts/ws with your key in the Authorization header. Then:

You sendMeaning
{"type":"config","voice_id":…,"language":…,"output_format":"pcm_s16le","sample_rate":8000,"speed":1.0,"binary":false}Once, first. Formats: pcm_s16le, ulaw, alaw.
{"type":"speak","context_id":"turn-1","text":"…"}Any number; spoken in order. Up to 20 may wait in the queue.
{"type":"cancel","context_id":"turn-1"}Barge-in: stops it (between sentences) or removes it from the queue.
{"type":"ping"}Keep-alive. Idle connections close after 120 s; any connection after 1 hour.
You receiveMeaning
{"type":"ready","session_id":…,"balance":"…"}Connected.
{"type":"audio","context_id":…,"seq":0,"data":"<base64>"}Audio as it is generated.
{"type":"done","context_id":…,"chars_billed":…,"cost":"…","balance":"…","audio_ms":…}That utterance is complete. With Hinglish, also "spoken_text": the Devanagari actually spoken.
{"type":"cancelled","context_id":…}Your cancel took effect.
{"type":"error","context_id":…,"code":"TTS_…","message":…}That utterance failed; the connection stays open.

Binary frames (config "binary": true) avoid base64: "DVA1" · 1 byte length of context_id · context_id · 4-byte big-endian seq · raw audio.

Python

import asyncio, base64, json, os, websockets   # pip install websockets

async def main():
    async with websockets.connect("wss://tts.dotvoice.in/api/v1/tts/ws",
            additional_headers={"Authorization": f"Bearer {os.environ['DOTVOICE_KEY']}"}) as ws:
        print(json.loads(await ws.recv()))                       # ready
        await ws.send(json.dumps({"type": "config", "voice_id": "dv_en_in_female_01",
                                  "language": "en-IN", "output_format": "ulaw", "sample_rate": 8000}))
        await ws.recv()                                          # configured
        await ws.send(json.dumps({"type": "speak", "context_id": "turn-1", "text": "How can I help you today?"}))
        audio = b""
        while True:
            m = json.loads(await ws.recv())
            if m["type"] == "audio":
                audio += base64.b64decode(m["data"])             # play or forward to RTP here
            elif m["type"] in ("done", "error", "cancelled"):
                print(m); break
        open("turn-1.ulaw", "wb").write(audio)

asyncio.run(main())

Node.js

import WebSocket from "ws";                                   // npm install ws
const ws = new WebSocket("wss://tts.dotvoice.in/api/v1/tts/ws",
  { headers: { Authorization: `Bearer ${process.env.DOTVOICE_KEY}` } });
ws.on("open", () => {
  ws.send(JSON.stringify({ type: "config", voice_id: "dv_en_in_female_01", language: "en", output_format: "pcm_s16le", sample_rate: 16000 }));
  ws.send(JSON.stringify({ type: "speak", context_id: "a", text: "Hello!" }));
});
ws.on("message", (raw) => {
  const m = JSON.parse(raw);
  if (m.type === "audio") player.write(Buffer.from(m.data, "base64"));
  if (m.type === "done") console.log("cost ₹" + m.cost, "balance ₹" + m.balance);
});
// Caller interrupted the bot:  ws.send(JSON.stringify({ type: "cancel", context_id: "a" }));

From a browser

Browsers cannot send headers on a WebSocket, and a key must never reach a web page. Your server calls POST /api/v1/auth/ws-token (with the key) and passes the returned token to the page, which connects to …/api/v1/tts/ws?token=<token>. Tokens work once and expire after 60 seconds.

Telephony (Asterisk, SIP, IVR)

Request "output_format": "ulaw", "sample_rate": 8000 — G.711 μ-law, exactly what Asterisk and most SIP trunks carry (160 bytes per 20 ms frame). For a fixed prompt, use REST once and keep the file; for a live agent, use the WebSocket and write each audio chunk to your RTP stream or AudioSocket as it arrives, sending cancel when the caller starts speaking.

curl https://tts.dotvoice.in/api/v1/tts/synthesize -H "Authorization: Bearer $DOTVOICE_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Press 1 to pay now.","voice_id":"dv_en_in_female_01","language":"en-IN","output_format":"ulaw","sample_rate":8000}' \
  -o /var/lib/asterisk/sounds/custom/pay-now.ulaw        # then Playback(custom/pay-now)

Hinglish (Hindi typed in English letters)

Send "language": "hi-Latn" with a Hindi voice and type the way you would on WhatsApp. Hindi words are converted to Devanagari before speaking; English words stay English; numbers, amounts, dates and times are read in Hindi.

Aapka payment 12/03/2026 tak due hai, amount ₹2,500 hai
→ आपका payment बारह March दो हज़ार छब्बीस तक due है, amount दो हज़ार पाँच सौ रुपये है.

Speech to text beta

Send a recording, get the text. English, Hindi and Hinglish; up to 10 minutes and 25 MB per file; any common format (WAV, MP3, OGG/Opus, M4A, WEBM, FLAC) or raw telephony audio. Billed per started second of audio at ₹0.50 per minute, from the same wallet; refunded if transcription fails on our side. The audio is deleted as soon as it is transcribed.

curl "https://tts.dotvoice.in/api/v1/stt/transcribe?language=hi-Latn"   -H "Authorization: Bearer $DOTVOICE_KEY"   --data-binary @answer.wav
ParameterValues
languageen (English), hi (Hindi, Devanagari text), hi-Latn (Hinglish, Roman text: aapka payment kal hoga)
formatauto (default: detected from the file), or raw ulaw / alaw / pcm_s16le with sample_rate (default 8000)
waittrue (default): audio up to 30 s is answered in the same response. false: always return a job id at once.
request_idYour own id for the request (optional, unique per request).

The body is the audio itself, or a multipart form with the audio in field file. Short audio returns 200; longer audio returns 202 with a job to poll:

{"success": true, "id": "stt_7Hk2Qp9xLm3a", "status": "done", "language": "hi-Latn",
 "duration_seconds": 4.2, "text": "haan main kal tak payment kar dunga",
 "segments": [{"start": 0.0, "end": 4.2, "text": "haan main kal tak payment kar dunga"}]}

GET https://tts.dotvoice.in/api/v1/stt/jobs/stt_7Hk2Qp9xLm3a              -> the same JSON (status: queued | running | done | failed)
GET https://tts.dotvoice.in/api/v1/stt/jobs/stt_7Hk2Qp9xLm3a?format=srt   -> subtitles  (format=txt: plain text)

Headers on the transcribe response: X-DotVoice-Seconds-Billed, X-DotVoice-Cost, X-DotVoice-Balance. Processing takes about as long as the audio. Errors: STT_BAD_AUDIO (422, unreadable file), STT_TOO_LONG / STT_TOO_LARGE (413), STT_UNAVAILABLE (503, retry), TTS_INSUFFICIENT_BALANCE (402). Make sure you have the caller's consent to record and transcribe.

Request fields

textUp to 2,000 characters by default. Hindi in Devanagari; English words may stay in English. Hindi typed in English letters: send "language": "hi-Latn" and it is converted for you.
voice_iddv_hi_female_01 — Aarohi · Hindi female; dv_en_in_female_01 — Kavya · English (India) female; dv_kn_female_01 — Kaveri · Kannada female; dv_te_female_01 — Godavari · Telugu female; dv_bn_female_01 — Ganga · Bengali female; dv_mr_female_01 — Krishna · Marathi female; dv_hi_male_01 — Arjun · Hindi male; dv_en_in_male_01 — Vikram · English (India) male; dv_hi_female_02 — Meera · Hindi female; dv_gu_female_01 — Narmada · Gujarati female; dv_pa_female_01 — Simran · Punjabi female; dv_ta_female_01 — Vaigai · Tamil female; dv_ml_female_01 — Periyar · Malayalam female; dv_bho_female_01 — Saryu · Bhojpuri female
languagehi, mixed-hi-en, en-IN, en, te (Telugu), bn (Bengali), mr (Marathi), gu (Gujarati), pa (Punjabi), ta (Tamil), ml (Malayalam), bho (Bhojpuri), kn (Kannada — numbers, amounts, dates and English words are read in Kannada), hi-Latn (Hinglish typed in English letters — converted to Devanagari for the Hindi voices, see Hinglish)
output_formatwav (REST only), pcm_s16le, ulaw, alaw
sample_rate8000, 16000, 22050, 24000
speed0.2 – 2.0 (default 1.0)
request_idOptional, up to 48 characters. Reusing one is refused with 409 and never charged twice — so retries are safe.

Billing & limits

Errors

{"success": false, "error": {"code": "TTS_INSUFFICIENT_BALANCE", "message": "Wallet balance ₹0.0030 is below this request's cost ₹0.0140. Add credit to continue."}}
HTTPcodeMeaning
401 / 403TTS_UNAUTHENTICATED / TTS_FORBIDDENMissing or invalid key.
400TTS_INVALID_REQUESTThe request was not valid.
402TTS_INSUFFICIENT_BALANCEYour wallet balance is too low for this request.
403TTS_ACCOUNT_INACTIVEThis account is not active.
404TTS_VOICE_NOT_FOUNDThe requested voice is not available.
409TTS_DUPLICATE_REQUESTA request with this request_id was already accepted; it was not charged again.
413TTS_TEXT_TOO_LONGThe text is longer than your per-request limit.
429TTS_RATE_LIMITEDRequest rate limit reached for this account.
429TTS_CONCURRENCY_LIMITToo many requests in progress for this account.
429TTS_AT_CAPACITYSpeech synthesis is at capacity.
503TTS_MODEL_UNAVAILABLESpeech synthesis is temporarily unavailable.

429 responses include Retry-After (seconds).

Voice credits

The Hindi voice Aarohi was trained by DotVoice on the SYSPIN_S1.0 Corpus — A TTS Corpus of 900+ hours in nine Indian Languages (Abhayjeet et al., Indian Institute of Science, Bengaluru, 2025), licensed CC BY 4.0. The Indian English voice Kavya was trained by DotVoice on the IISc SPICOR TTS corpus (Indian Institute of Science, Bengaluru), licensed CC BY 4.0. The English voices Joe and Kathleen are Piper voices trained on CC0 data; Kathleen's base model credits the Hi-Fi TTS dataset (NVIDIA, CC BY 4.0).

All endpoints

GET/api/v1/voicesList Voices
GET/api/v1/voices/{voice_id}Get Voice
GET/api/v1/modelsList Models
POST/api/v1/tts/synthesizeComplete audio as raw bytes. Metadata rides in the response headers.
POST/api/v1/tts/streamChunked stream. First bytes leave as soon as the model produces them.
POST/api/v1/transliterateWhat would be spoken, without synthesising: Roman Hindi -> Devanagari.
POST/api/v1/tts/requests/{request_id}/cancelStop an in-flight synthesis. Used for barge-in.
POST/api/v1/stt/transcribeSpeech to text. Send the audio as the request body (any common format, or raw ulaw/alaw/pcm_s16le
GET/api/v1/stt/jobs/{job_id}A transcription job: status, and the transcript when done. format=json | txt | srt.
POST/api/v1/auth/ws-tokenA single-use token, valid 60 seconds, for opening the WebSocket from a
GET/api/v1/accountThe calling customer's balance, rate and limits.
GET/api/v1/usageCharacters, requests and cost per day (UTC days), most recent last.
WS/api/v1/tts/wsWebSocket streaming (above).

Machine-readable: /api/v1/openapi.json (OpenAPI 3 — import into Postman or generate a client).