> This page is for Model APIs.

> Sarvam Voice Agents (Samvaad) is a voice AI agent platform for Indian languages: build, test and deploy AI calling agents on your own phone numbers, from ₹3 a minute. Start here: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Dictate API

> Turn speech into text a person can send, such as a chat message, a to-do list, a CRM record or meeting minutes. One API for short clips, long recordings and live dictation.

> **Note**
>
> The SDK examples use the pre-release SDKs: `sarvamai` 0.1.49a1 for Python and 1.1.22-alpha.1 for
> JavaScript. The install commands are in the [Quickstart](#quickstart).

Sarvam Dictate is a dictation API that turns audio into the text a person meant to type, in English and 22 Indian languages. One call pairs Saaras v4, Sarvam's ASR model, which hears the audio and writes the transcript, with Sarvam 105B. Sarvam 105B reads that transcript together with context from your app: a vocabulary of the user's names and terms, a document such as a CRM record or product list, a line about the situation, and a style. It returns the finished text next to the raw transcript and can apply up to 1000 keyterms.

**Want to try it right now?** [Jump to the quickstart](#quickstart).

## See it work

#### Clean text

Drop the "um", the repeats and the false starts, and keep the corrected version. This is the default.

**`You say`**

```text title="You say" wordWrap
Um, let's meet on Tuesday, no sorry, Wednesday at the main office.
```

**`Dictate returns in text`**

```text title="Dictate returns in text" wordWrap
Let's meet on Wednesday at the main office.
```

#### Chat message

Pick the script of the text with `mode`: Hinglish for a chat, or Roman Hindi when your app shows Latin letters only.

**`You say (Hindi)`**

```text title="You say (Hindi)" wordWrap
कल शाम को घर आ जाना, मम्मी ने खाना बनाया है। और हाँ, मेरे लिए एक chocolate cake ले आना please।
```

**`mode=codemix`**

```text title="mode=codemix" wordWrap
कल शाम को घर आ जाना, मम्मी ने खाना बनाया है और हाँ, मेरे लिए एक chocolate cake ले आना please।
```

**`mode=translit`**

```text title="mode=translit" wordWrap
Kal shaam ko ghar aa jaana, Mummy ne khaana banaya hai aur haan mere liye ek chocolate cake le aana please.
```

#### Your names

Send the names of this recording in `vocabulary`, and Dictate writes them your way.

**`You say`**

```text title="You say" wordWrap
Hi, this is Meera from Velqora Support. I spoke to Vyshnavi Raghunathan about her Velqora Fiber connection.
```

**`Without a vocabulary`**

```text title="Without a vocabulary" wordWrap
Hi, this is Meera from Velcore support. I spoke to Vaishnavi Raghunathan about her Velcore fiber connection.
```

**`With vocabulary=[Velqora, Velqora Fiber, Vyshnavi Raghunathan]`**

```text title="With vocabulary=[Velqora, Velqora Fiber, Vyshnavi Raghunathan]" wordWrap
Hi, this is Meera from Velqora support. I spoke to Vyshnavi Raghunathan about her Velqora Fiber connection.
```

#### Bullets, in English

Change the form of the text with `style.rules`: here, translate it and put each task on its own line.

**`You say (Tamil)`**

```text title="You say (Tamil)" wordWrap
நான் வங்கிக்கு போகணும். அப்புறம் அம்மாவுக்கு phone பண்ணணும். அதுக்கப்புறம் வெள்ளிக்கிழமை rail ticket book பண்ணணும்.
```

**`style.rules`**

```text title="style.rules" wordWrap
Translate the text into English. Put each task on its own line, as a bullet that starts with "- ".
```

**`Dictate returns in text`**

```text title="Dictate returns in text" wordWrap
- I need to go to the bank.
- Then I need to phone my mother.
- After that, I need to book a rail ticket on Friday.
```

#### JSON for a form

Describe the fields you want in `output_rules`, and get them from the whole recording in `output.text`.

**`You say (a Hindi sales call)`**

```text title="You say (a Hindi sales call)" wordWrap
नमस्ते, मैं सुनीता कुलकर्णी बोल रही हूँ, नाशिक से। मुझे एक हज़ार लीटर के चालीस पानी के टैंक चाहिए। मेरा नंबर है नौ आठ दो दो शून्य चार एक सात तीन पाँच। एक टैंक का रेट छह हज़ार आठ सौ रुपये रखिए।
```

**`Dictate returns in output.text`**

```json title="Dictate returns in output.text"
{
  "buyer_name": "Sunita Kulkarni",
  "buyer_city": "Nashik",
  "buyer_phone": "9822041735",
  "product": "water tanks of 1,000 liters",
  "quantity": 40,
  "unit_price_inr": 6800
}
```

Every example here was produced by running the code on the live API. The [recipes](/api/api-guides-tutorials/dictate/best-practices) show the code for each one.

## What you can build

#### [Voice notes to chat messages](/api/api-guides-tutorials/dictate/best-practices#chat-messages-choose-the-script)

Hinglish, Roman Hindi or one script, with no fillers.

#### [Forms and CRM records](/api/api-guides-tutorials/dictate/how-to/structured-output)

Speak a sales call, get a JSON record.

#### [Meeting minutes](/api/api-guides-tutorials/dictate/how-to/long-recordings)

Upload an hour of audio, get a summary and action items.

#### [Live dictation in an app](/api/api-guides-tutorials/dictate/how-to/live-dictation)

Show partial text while the user speaks, then one finished text after each pause.

## Which route should I use?

Pick the route by the audio you have.

| Your audio                       | Route                                                                                       | You get                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| A file of **30 seconds or less** | [Clip](/api-reference/dictate/clip) `POST /v2/dictate`                                      | The text in the response                                                      |
| A file of **up to 1 hour**       | [Job](/api/api-guides-tutorials/dictate/how-to/long-recordings) `POST /v2/dictate/jobs`     | A job to poll, or a callback                                                  |
| A **live microphone**            | [Live socket](/api/api-guides-tutorials/dictate/how-to/live-dictation) `WSS /v2/dictate/ws` | Partial text while the person speaks, then one finished text after each pause |

Not sure? Start with a clip. It is the shortest path, and the quickstart below uses it.

## Quickstart

#### Get a key and install the SDK

[Create an API key on the dashboard](https://indus.sarvam.ai/key-management?ref=docs) and set it as `SARVAM_API_KEY`. Dictate reads the key from the `api-subscription-key` header or from `Authorization: Bearer <key>`: either one is enough. You need Python 3.8 or later, or Node.js 18 or later.

#### Python

```bash
pip install "sarvamai==0.1.49a1"
```

#### JavaScript

```bash
npm install sarvamai@1.1.22-alpha.1
```

#### Get a test clip

Any recording of 30 s or less works: WAV, MP3, M4A and [more](/api/api-guides-tutorials/dictate/how-to/audio-and-languages). Record your own, or make one with the tool for your system:

#### Any system (Python)

Use Sarvam's own text to speech. It needs the SDK and `SARVAM_API_KEY` from step 1.

```python
import base64, os
from sarvamai import SarvamAI

client = SarvamAI(
    api_subscription_key=os.environ["SARVAM_API_KEY"],
)

audio = client.text_to_speech.convert(
    text=(
        "Um, let's meet on Tuesday, no sorry, "
        "Wednesday at the main office."
    ),
    language_code="en-IN",
    model="bulbul:v3",
    speech_sample_rate=16000,
)
with open("note.wav", "wb") as f:
    f.write(base64.b64decode(audio.audios[0]))
```

#### macOS

```bash
say -v Samantha -o note.aiff "Um, let's meet on Tuesday, no sorry, Wednesday at the main office."
afconvert -f WAVE -d LEI16@16000 note.aiff note.wav
```

#### Linux

Install `espeak-ng` with your package manager, for example `sudo apt install espeak-ng`.

```bash
espeak-ng -w note.wav "Um, let's meet on Tuesday, no sorry, Wednesday at the main office."
```

#### Windows

In PowerShell:

```powershell
Add-Type -AssemblyName System.Speech
$speech = New-Object System.Speech.Synthesis.SpeechSynthesizer
$speech.SetOutputToWaveFile("note.wav")
$speech.Speak("Um, let's meet on Tuesday, no sorry, Wednesday at the main office.")
$speech.Dispose()
```

#### Make your first call

Use [`POST /v2/dictate`](/api-reference/dictate/clip).

#### Python

```python
import os
from sarvamai import SarvamAI

client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])

with open("note.wav", "rb") as f:
    response = client.dictate.transcribe(file=f, language_code="en-IN")

print(response.text)        # the finished text
print(response.transcript)  # what speech recognition heard
print(response.degraded)    # None when the text was finished
```

#### JavaScript

```javascript
import fs from "fs";
import { SarvamAIClient } from "sarvamai";

const client = new SarvamAIClient({ apiSubscriptionKey: process.env.SARVAM_API_KEY });

const response = await client.dictate.transcribe({
  file: fs.createReadStream("note.wav"),
  language_code: "en-IN",
});

console.log(response.text); // the finished text
console.log(response.transcript); // what speech recognition heard
console.log(response.degraded); // null when the text was finished
```

#### curl

```bash
curl -sS https://api.sarvam.ai/v2/dictate \
  -H "api-subscription-key: $SARVAM_API_KEY" \
  -F file=@note.wav \
  -F language_code=en-IN
```

**`Response (trimmed)`**

```json title="Response (trimmed)" wordWrap
{
  "text": "Let's meet on Wednesday at the main office.",
  "transcript": "um, let's meet on Tuesday. No sorry, Wednesday at the main office.",
  "degraded": null,
  "corrections": [],
  "usage": { "audio_duration_s": 4.01, "words": 12, "llm_input_tokens": 5366, "llm_output_tokens": 12 }
}
```

## What you get back

| Field         | What it is                                                                                                                               | Use it for                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `text`        | The finished text                                                                                                                        | Show it to people                   |
| `transcript`  | What speech recognition heard, unchanged                                                                                                 | Search and audit                    |
| `corrections` | Each name that `vocabulary` or `context.reference` changed                                                                               | Show the user what changed          |
| `degraded`    | `null` when the finishing step ran. Otherwise the reason it did not, and `text` is the raw transcript                                    | Check it in every response          |
| `output`      | A new text made from the whole recording. Only when you send `output_rules`                                                              | JSON for a form, a summary, a reply |
| `usage`       | Audio length in seconds, word count and model tokens. It has no price: work out the cost from the audio length and your per-minute price | Cost tracking                       |

## Customize the request

Each setting answers one question. Leave a field out to keep its default.

| Question                                              | Setting                                                   | Guide                                                                                         |
| ----------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| What language is it?                                  | `language_code`: one of 23 codes, or `auto`               | [Audio and languages](/api/api-guides-tutorials/dictate/how-to/audio-and-languages)           |
| Where does the text go: a chat, a document, a record? | `mode`: `codemix`, `transcribe`, `translit` or `verbatim` | [Choose the script](/api/api-guides-tutorials/dictate/how-to/choose-script)                   |
| How much do we tidy it?                               | `style.preset`: `none`, `light` or `clean`                | [Best Practices](/api/api-guides-tutorials/dictate/best-practices#clean-text-light-or-clean)  |
| What form must the text have: bullets, English, ₹?    | `style.rules`                                             | [Change the form](/api/api-guides-tutorials/dictate/how-to/style-rules)                       |
| Which names must be right?                            | `vocabulary`, `context.reference`                         | [Get names right](/api/api-guides-tutorials/dictate/how-to/custom-vocabulary)                 |
| What else do we need from the recording?              | `output_rules`                                            | [Get JSON, summaries and answers](/api/api-guides-tutorials/dictate/how-to/structured-output) |
| Must the text stay the same over time?                | `model`: pin a dated snapshot                             | [Pin a model version](/api/api-guides-tutorials/dictate/how-to/pin-model-version)             |

## Dictate or Speech-to-Text?

Both turn speech into text. Choose by what the text is for.

Here is the same recording through each.

**`Speech-to-Text (Saaras) returns`**

```text title="Speech-to-Text (Saaras) returns" wordWrap
Um, so I was, I was thinking that we could, you know, like maybe go there tomorrow and and see the place.
```

**`Dictate returns`**

```text title="Dictate returns" wordWrap
So I was thinking that we could maybe go there tomorrow and see the place.
```

|                                   | Dictate                                                                                          | [Speech-to-Text](/api/api-guides-tutorials/speech-to-text/which-api-to-use) (Saaras) |
| --------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| **What you get**                  | Finished text a person can send: punctuation, no "um" or false starts, numbers as digits         | The transcript of what was said, in the mode you pick                                |
| **Your names and rules**          | `vocabulary` and `context.reference` fix names. `style.rules` set the form (bullets, English, ₹) | Keyterm prompting. No style rules                                                    |
| **A new text from the recording** | `output_rules` gives JSON, a summary, answers or a reply                                         | No                                                                                   |
| **Long audio**                    | A job: up to 1 hour                                                                              | Batch: up to 2 hours, up to 20 files per job                                         |
| **Live audio**                    | WebSocket: partial text while speaking, then one finished text for each pause                    | Realtime: partial transcripts for voice agents, with `config.update` and VAD tuning  |

**Use <mark>Dictate</mark> when** the text goes straight to a person or a system: a chat message, a note, a CRM record or form, meeting minutes. The finishing, the names and the JSON are done for you.

**Use <mark>Speech-to-Text (Saaras)</mark> when** you need the raw transcript, for search or analytics, or the longest files, or a voice agent that reacts to partial transcripts while the user is still speaking.

You can use both: keep the Speech-to-Text transcript for your records, and use Dictate for the text you show.

## What Dictate doesn't do

> **Warning**
>
> If you are comparing APIs, check this list first. Dictate does **not** offer:
>
> * **Subtitle files.** There is no SRT or VTT output.
> * **Browser tokens.** There are no short-lived tokens, so a browser or app cannot open the socket safely. Open it from your server.
> * **Translation as a mode.** There is no `translate` mode. Ask for it in `style.rules`.
>
> [Limitations](/api/api-guides-tutorials/dictate/limitations) lists every limit.

## Pricing and rate limits

* **Price.** Dictate costs **₹0.50 per minute** of audio on Pay as you go, and less on Pro, Growth and Business. Every response has a `usage` field with the audio length in seconds (`audio_duration_s`) and the token counts. It does not show an amount, so multiply the minutes by your price. All prices are on the [pricing page](/api/getting-started/pricing#dictate).
* **Rate limits.** They are the same as Speech-to-Text, and are listed under [Dictate limits](/api/getting-started/pricing#dictate-limits).
* **Over a limit.** The API answers `429` with a `Retry-After` header. The SDKs wait and try again by themselves. See [Handle errors and retries](/api/api-guides-tutorials/dictate/how-to/error-handling).

## Next steps

#### [Best Practices](/api/api-guides-tutorials/dictate/best-practices)

Recipes with Python and JavaScript SDK code: chat messages, names, JSON, meeting minutes, live dictation.

#### [How-to guides](/api/api-guides-tutorials/dictate/how-to/custom-vocabulary)

One task per page: names, form, JSON, long files, live dictation, versions and errors.

#### [Limitations](/api/api-guides-tutorials/dictate/limitations)

What Dictate does not do, and its limits.

#### [API reference](/api-reference/dictate/clip)

Every field, limit and error of the clip, job and WebSocket routes.