API reference

Introduction

Dhvni AI does two things. Text to speech turns text into audio in a voice set up for your account. Speech to text turns a recording into text. Both handle Hindi, English and Hinglish, including sentences that switch languages halfway.

Every request goes to https://api.dhvni.in over HTTPS. You send JSON, except for recordings, which go up as multipart form data. Audio comes back as the audio itself, ready to save or play.

Endpoints

Quickstart

Three steps from no account to your first audio file.

1. 1

   Get an API key

   Request access and tell us what you are building. We create your account and send you an API key, shown once. Keep it on your server, for example in an environment variable.

   ShellCopy Shell

   export DHVNI_API_KEY="paste your key here"

2. 2

   Find your voice id

   Our team sets up each voice with the speaker's consent and adds it to your account. List your voices to get its id.

   cURLCopy cURL

   curl https://api.dhvni.in/v1/voices \
     -H "Authorization: Bearer $DHVNI_API_KEY"

3. 3

   Speak your first line

   Send text with the voice id. The audio comes back as an mp3 file.

   cURLCopy cURL

   curl https://api.dhvni.in/v1/tts \
     -H "Authorization: Bearer $DHVNI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "voice_id": "voice_7f3a91c2d4e85b60",
       "text": "नमस्ते, आज हम photosynthesis पढ़ेंगे।"
     }' \
     -o hello.mp3

Authentication

Send your API key as a bearer token in the Authorization header of every request.

Authorization: Bearer $DHVNI_API_KEY

Keep the key on your server. Anyone who has it can use your account, so never put it in a web page or in an app you ship. If a key leaks, write to support@dhvni.in so we can turn it off and issue a new one.

Browser tokens

POST/v1/tokens

Browsers cannot set headers on a WebSocket, so a web page cannot send your key to WS /v1/tts/stream. Instead, your backend asks for a short lived token and passes it to the page, which connects with ?token=.

curl -X POST https://api.dhvni.in/v1/tokens \
  -H "Authorization: Bearer $DHVNI_API_KEY"

{
  "token": "vgs_...",
  "expires_at": 1793059320
}

Voices

GET/v1/voices

Our team sets up voices with the speaker's consent and adds them to your account; in this version you do not create them through the API. List them to fill a voice picker or to find a voice_id. The newest voice comes first.

curl https://api.dhvni.in/v1/voices \
  -H "Authorization: Bearer $DHVNI_API_KEY"

{
  "voices": [
    {
      "id": "voice_7f3a91c2d4e85b60",
      "name": "Kavya, teacher",
      "speaker_name": "Kavya Sharma",
      "status": "active",
      "shared": false,
      "reference_seconds": 1264.8,
      "created_at": 1792966000.41,
      "activated_at": 1793052400.87
    }
  ]
}

Voice fields

Need another voice? See voice cloning for what to send us.

Text to speech

POST/v1/tts

Send text and a voice id as JSON. The audio comes back as one file or, with stream set to true, as a stream that starts in about 0.3 seconds and keeps coming while it is generated.

Request body

curl https://api.dhvni.in/v1/tts \
  -H "Authorization: Bearer $DHVNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "voice_7f3a91c2d4e85b60",
    "text": "देखो बेटा, mitochondria को cell का powerhouse कहते हैं।",
    "format": "mp3",
    "quality": "hq"
  }' \
  -o lesson.mp3

Audio formats

Every format is mono, at the sample_rate you ask for.

Response

A 200 response body is the audio itself, with these headers.

HTTP/1.1 200 OK
content-type: audio/mpeg
x-request-id: req_4c1e9a7b2f6d8e03
x-audio-seconds: 4.86

Streaming text to speech

WS/v1/tts/stream

Use the WebSocket when text arrives a piece at a time, for example from your own LLM. Send text as it is written; each sentence is spoken as soon as it is complete, while the next one is still on its way. Audio comes back as raw PCM frames.

wss://api.dhvni.in/v1/tts/stream?voice_id=voice_7f3a91c2d4e85b60&sample_rate=24000&quality=fast

Connecting

From a server, send the Authorization header as usual. From a browser, get a token from your backend and add it as token. There is no format here: audio is always 16 bit PCM at sample_rate.

Messages you send

Send each message as a JSON text frame.

A sentence is complete when its end mark (., !, ? or ।) is followed by a space or a new line, so a decimal such as 3.14 is never split. The first piece may stop at a comma so the first audio comes sooner. After that, short sentences are grouped so the intonation does not restart every few words.

Messages you receive

An unknown type, or a frame that is not JSON, gets an error message and the connection stays open. If the connection cannot be accepted, it closes with one of these codes.

Example

// 1. Get a token from your backend (see Authentication)
const { token } = await fetch("/voice-token", { method: "POST" }).then((r) => r.json());

// 2. Connect
const ws = new WebSocket(
  `wss://api.dhvni.in/v1/tts/stream?voice_id=voice_7f3a91c2d4e85b60&sample_rate=24000&token=${token}`
);
ws.binaryType = "arraybuffer";

ws.onmessage = (e) => {
  if (typeof e.data !== "string") return player.write(e.data); // PCM16 audio
  const msg = JSON.parse(e.data);
  if (msg.type === "error") console.error(msg.message);
};

// 3. Send text as your LLM writes it, then close
ws.onopen = async () => {
  for await (const delta of llm.stream(prompt)) {
    ws.send(JSON.stringify({ type: "text", text: delta }));
  }
  ws.send(JSON.stringify({ type: "close" }));
};

Speech to text

POST/v1/stt

Upload a recording as multipart form data and get the transcript back. Hindi comes back in Devanagari and English words in English letters, the way the sentence was spoken.

Form fields

curl https://api.dhvni.in/v1/stt \
  -H "Authorization: Bearer $DHVNI_API_KEY" \
  -F file=@question.m4a \
  -F prompt="NCERT, mitochondria, Priya Ma'am"

Response

{
  "text": "सर, mitochondria को powerhouse क्यों कहते हैं?",
  "model": "dhvni-transcribe-1",
  "duration_seconds": 3.2,
  "request_id": "req_9b2d41e7c05a6f38"
}

With response_format set to text, the body is the transcript alone, as plain text. The X-Request-Id header is set either way.

Models and usage

Models

GET/v1/models

Lists the two models: dhvni-voice-1 for text to speech and dhvni-transcribe-1 for speech to text. Each endpoint has one model, so you can leave model out of every request.

curl https://api.dhvni.in/v1/models \
  -H "Authorization: Bearer $DHVNI_API_KEY"

{
  "models": [
    {
      "id": "dhvni-voice-1",
      "type": "text-to-speech",
      "languages": ["hi", "en", "hinglish"]
    },
    {
      "id": "dhvni-transcribe-1",
      "type": "speech-to-text",
      "languages": ["hi", "en", "hinglish"]
    }
  ]
}

Usage

GET/v1/usage

Totals for each metered unit over a window of time. Without parameters, the window is the last 30 days.

curl "https://api.dhvni.in/v1/usage?since=1790467200&until=1793059200" \
  -H "Authorization: Bearer $DHVNI_API_KEY"

{
  "since": 1790467200.0,
  "until": 1793059200.0,
  "usage": [
    { "metric": "stt_seconds", "quantity": 8214.6, "unit": "seconds" },
    { "metric": "tts_characters", "quantity": 1482306.0, "unit": "characters" },
    { "metric": "tts_seconds", "quantity": 96120.45, "unit": "seconds" }
  ]
}

A metric with no usage in the window is left out. Usage is recorded when each request or stream finishes, and quantities are rounded to two decimals.

Errors and limits

Errors come back as JSON with a detail message that says what went wrong.

{
  "detail": "Voice voice_7f3a91c2d4e85b60 not found on this account."
}

When a field fails validation, the status is 422 and detail is a list, with one entry per field: loc says where the field is and msg what is wrong with it.

{
  "detail": [
    {
      "type": "literal_error",
      "loc": ["body", "sample_rate"],
      "msg": "Input should be 16000, 22050, 24000, 44100 or 48000",
      "input": 32000
    }
  ]
}

Limits

Limits are per account. Over a limit, you get 429 with a Retry-After header in seconds; on the WebSocket, the same limits arrive as an error message with status 429. If you need more room, write to support@dhvni.in.

// Retries a request when the API asks you to wait.
async function withRetry(send, tries = 3) {
  for (let attempt = 1; ; attempt++) {
    const res = await send();
    if (![429, 503].includes(res.status) || attempt === tries) return res;
    const seconds = Number(res.headers.get("retry-after") ?? 2);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

const res = await withRetry(() => fetch("https://api.dhvni.in/v1/tts", options));

Writing text for Hindi speech

Dhvni reads Hinglish the way it is written, so how you write the text decides how it sounds. Three habits make the biggest difference.

• Hindi in Devanagari, English in English letters

  Keep each word in the script of its language. English terms are then said the way an Indian speaker says them.

  Write: देखो बेटा, mitochondria cell का powerhouse है।

  Avoid: Dekho beta, mitochondria cell ka powerhouse hai.

  Hindi typed in English letters picks up an English accent.

• Numbers as words

  Write numbers, dates and ranges the way they should be said, in the language of the sentence around them.

  Write: आपका refund तीन से पाँच working days में आ जाएगा।

  Avoid: आपका refund 3-5 working days में आ जाएगा।

  Digits and symbols leave the reading to chance.

• Finish each sentence

  End sentences with । or a full stop, and questions with a question mark. Text is split into pieces at these marks before it is spoken.

  Write: आपकी EMI पाँच तारीख को due है। क्या मैं payment link भेज दूँ?

  Avoid: आपकी EMI पाँच तारीख को due है क्या मैं payment link भेज दूँ

  Without end marks, two sentences read as one.

Also worth knowing

• Markdown symbols such as *, # and _, list bullets and emoji are removed before speaking, so you can pass LLM output straight in.
• Spaces and punctuation count as characters, and so does each Devanagari vowel sign: बेटा is four characters. See pricing.
• Transcripts follow the same rules: Hindi in Devanagari, English words in English letters. Pass names and subject words in prompt to get them spelled your way.