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
| Style | Endpoint | Use it when |
|---|---|---|
| REST | POST /tts/synthesize | You want a complete file — IVR prompts, downloads, batch jobs. |
| HTTP streaming | POST /tts/stream | Start playback while audio is generated; one utterance per request. |
| WebSocket | wss /tts/ws | Live 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 send | Meaning |
|---|---|
| {"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 receive | Meaning |
|---|---|
| {"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 दो हज़ार पाँच सौ रुपये है.
- The exact text spoken comes back in X-DotVoice-Spoken-Text (URL-encoded UTF-8) on REST and HTTP streaming, and as spoken_text in the WebSocket done message. For very long texts the header is replaced by X-DotVoice-Spoken-Text-Omitted: too-long.
- POST /api/v1/transliterate with {"text": "…", "voice_id": "…"} returns spoken_text and the uncertain_words worth checking, without generating audio. Free of charge.
- Billing is on the characters you send, not on the converted text.
- Names and brands we do not know may be spelt as they sound; check uncertain_words and add them to your pronunciation dictionary — it applies to every API and Studio request in Hinglish.
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
| Parameter | Values |
|---|---|
| language | en (English), hi (Hindi, Devanagari text), hi-Latn (Hinglish, Roman text: aapka payment kal hoga) |
| format | auto (default: detected from the file), or raw ulaw / alaw / pcm_s16le with sample_rate (default 8000) |
| wait | true (default): audio up to 30 s is answered in the same response. false: always return a job id at once. |
| request_id | Your 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
| text | Up 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_id | dv_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 |
| language | hi, 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_format | wav (REST only), pcm_s16le, ulaw, alaw |
| sample_rate | 8000, 16000, 22050, 24000 |
| speed | 0.2 – 2.0 (default 1.0) |
| request_id | Optional, up to 48 characters. Reusing one is refused with 409 and never charged twice — so retries are safe. |
Billing & limits
- You pay for the characters you send (spaces and punctuation included), at your rate per 1,000 characters. Cached audio is charged the same.
- REST and HTTP streaming are charged when the request is accepted; each WebSocket utterance when its synthesis starts (queued ones you cancel cost nothing).
- If synthesis fails on our side you are refunded automatically. If you cancel or disconnect, the charge stands.
- Every refusal — invalid input, low balance, limits — happens before any money moves.
- Default limits per account: 60 requests per minute, 3 requests or WebSocket connections in progress at once. Your own limits are in GET /account.
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."}}
| HTTP | code | Meaning |
|---|---|---|
| 401 / 403 | TTS_UNAUTHENTICATED / TTS_FORBIDDEN | Missing or invalid key. |
| 400 | TTS_INVALID_REQUEST | The request was not valid. |
| 402 | TTS_INSUFFICIENT_BALANCE | Your wallet balance is too low for this request. |
| 403 | TTS_ACCOUNT_INACTIVE | This account is not active. |
| 404 | TTS_VOICE_NOT_FOUND | The requested voice is not available. |
| 409 | TTS_DUPLICATE_REQUEST | A request with this request_id was already accepted; it was not charged again. |
| 413 | TTS_TEXT_TOO_LONG | The text is longer than your per-request limit. |
| 429 | TTS_RATE_LIMITED | Request rate limit reached for this account. |
| 429 | TTS_CONCURRENCY_LIMIT | Too many requests in progress for this account. |
| 429 | TTS_AT_CAPACITY | Speech synthesis is at capacity. |
| 503 | TTS_MODEL_UNAVAILABLE | Speech 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/voices | List Voices |
| GET | /api/v1/voices/{voice_id} | Get Voice |
| GET | /api/v1/models | List Models |
| POST | /api/v1/tts/synthesize | Complete audio as raw bytes. Metadata rides in the response headers. |
| POST | /api/v1/tts/stream | Chunked stream. First bytes leave as soon as the model produces them. |
| POST | /api/v1/transliterate | What would be spoken, without synthesising: Roman Hindi -> Devanagari. |
| POST | /api/v1/tts/requests/{request_id}/cancel | Stop an in-flight synthesis. Used for barge-in. |
| POST | /api/v1/stt/transcribe | Speech 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-token | A single-use token, valid 60 seconds, for opening the WebSocket from a |
| GET | /api/v1/account | The calling customer's balance, rate and limits. |
| GET | /api/v1/usage | Characters, requests and cost per day (UTC days), most recent last. |
| WS | /api/v1/tts/ws | WebSocket streaming (above). |
Machine-readable: /api/v1/openapi.json (OpenAPI 3 — import into Postman or generate a client).