> 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 Best Practices

> Best practices and recipes for the Dictate API, with Python and JavaScript SDK code: voice notes to chat messages, lists, names that come out right, JSON for forms and CRMs, meeting minutes, and live dictation.

> **Note**
>
> The code uses the
> Sarvam [Python and JavaScript SDKs](/api/getting-started/sdks) (pre-release versions: Python `sarvamai` 0.1.49a1, JavaScript `sarvamai` 1.1.22-alpha.1).
> Every field and limit is in the [API reference](/api-reference/dictate/clip).

Dictate turns speech into text that a person can send: a chat message, a to-do list, a CRM record, meeting minutes. Pick the recipe that matches what you are building. New to Dictate? Make your [first call](/api/api-guides-tutorials/dictate/overview#make-your-first-call) first.

## Recipes at a glance

#### [Chat messages](#chat-messages-choose-the-script)

Pick the script of the text with `mode`: Hinglish, Roman Hindi, one script, or word for word.

#### [Clean text](#clean-text-light-or-clean)

Drop the "um", the repeats and the false starts, or keep every word.

#### [Bullets, English, rupees](#bullets-english-rupees-and-times)

Change the form of the text with `style.rules`: lists, translation, ₹, 24-hour time.

#### [Names your way](#names-your-way-vocabulary)

Make product, customer and medicine names come out right with `vocabulary`.

#### [Names from a document](#names-from-a-document-reference)

Send an agenda or a CRM record and let Dictate take the names from it.

#### [JSON, summaries, answers](#json-summaries-and-answers-output-rules)

Turn the whole recording into a form, a summary, answers or a reply with `output_rules`.

#### [Long recordings](#long-recordings-jobs)

Files up to 1 hour: upload a job and get meeting minutes back.

#### [Live dictation](#live-dictation-the-socket)

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

## How Dictate works

You send audio and some settings. Each setting answers one question:

* `mode`: where does the text go?
* `style.preset` and `style.rules`: how tidy, and what form?
* `vocabulary` and `context.reference`: which names must be right?
* `output_rules`: what else do we need from the recording?

The [Overview](/api/api-guides-tutorials/dictate/overview#customize-the-request) has the full table.

> **Tip**
>
> **The one rule to remember:** `style.rules` change the form of `text`. They never add or remove content.
> When you need something new (an email, a summary, JSON), use `output_rules`.

The recipes below use all three [routes](/api/api-guides-tutorials/dictate/overview#which-route-should-i-use): a clip, a job for long files, and the live socket.

## Set up the client

The recipes use one client and two small helpers. Paste this at the top of your script:

* `dictate()` opens a clip and sends it.
* `fixes()` prints the `corrections` of a response.

The SDK sends `style`, `vocabulary` and `context` for you: pass them as plain dicts and lists (Python) or objects (JavaScript). It also waits and retries after a `429` by itself. See [Handle errors and retries](/api/api-guides-tutorials/dictate/how-to/error-handling).

The recipes use short clips named after what they contain (`voice_note.mp3`, `support_note.wav`, and so on). Use a clip of your own with the same kind of content.

#### Python

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

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


def dictate(clip, **fields):
    """Send one clip (30 s or less) and return the response."""
    with open(clip, "rb") as f:
        return client.dictate.transcribe(file=f, **fields)


def fixes(res):
    """Print the vocabulary and reference changes."""
    for c in res.corrections:
        print(f"  {c.heard!r} -> {c.wrote!r} ({c.source})")
    if not res.corrections:
        print("  (no corrections)")
```

#### JavaScript

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

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

// Send one clip (30 s or less) and return the response.
const dictate = (clip, fields = {}) =>
  client.dictate.transcribe({ file: fs.createReadStream(clip), ...fields });

// Print the vocabulary and reference changes.
function fixes(res) {
  for (const c of res.corrections) {
  console.log(`  '${c.heard}' -> '${c.wrote}' (${c.source})`);
}
  if (!res.corrections.length) console.log("  (no corrections)");
}
```

In JavaScript, call `client.dictate.transcribe({ file: fs.createReadStream(clip), ...fields })` and pass the same objects. Fields keep the API names (`language_code`, `output_rules`, `sounds_like`).

## Chat messages: choose the script

**Use it when:** the text goes to a chat, a document or a record, and the reader expects a certain script.

`mode` picks the script. Here is one Hindi clip in all four modes.

#### Python

```python
for mode in ["codemix", "transcribe", "translit", "verbatim"]:
    res = dictate("voice_note.mp3", language_code="hi-IN",
                  mode=mode)
    first_line = res.text.splitlines()[0][:100]
    print(f"{mode:>10}: {first_line}")
```

#### JavaScript

```javascript
for (const mode of ["codemix", "transcribe", "translit", "verbatim"]) {
  const res = await dictate("voice_note.mp3", { language_code: "hi-IN", mode });
  const firstLine = res.text.split("\n")[0].slice(0, 100);
  console.log(`${mode.padStart(10)}: ${firstLine}`);
}
```

**`Output`**

```text title="Output" wordWrap
   codemix: देखिए भाई साहब, accident में बच्चे का खून काफी बह गया है। आप तो जानती हैं कि AB negative खून बड़ा मु
transcribe: देखिए भाई साहब, एक्सीडेंट में बच्चे का खून काफी बह गया है। आप तो जानती हैं कि AB नेगेटिव खून बड़ा मु
  translit: Dekhiye bhai sahab, accident mein bacche ka khoon kaafi beh gaya hai. Aap to jaanti hain ki AB negat
  verbatim: देखिए भाई साहब, एक्सीडेंट में बच्चे का खून काफी बह गया है। आप तो जानती हैं कि ए बी नेगेटिव खून बड़ा 
```

| Mode                   | What you get                                                   | Use it for                                                              |
| ---------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `codemix`              | The language in its own script, English words in Latin letters | Chat and messages: WhatsApp, Slack, email                               |
| `transcribe` (default) | One script for everything                                      | A document in one script, search, text that is read aloud               |
| `translit`             | Latin letters only                                             | People who type their language in Latin letters (Roman Hindi, Tanglish) |
| `verbatim`             | Every word as spoken, numbers as words, no edits               | An exact record: legal, medical, an ID read aloud                       |

> **Tip**
>
> Send `language_code` when you know it. `auto` works, but a known language is more reliable.

## Clean text: light or clean

**Use it when:** people say "um", repeat words and correct themselves ("Tuesday, no sorry, Wednesday"), and you want to decide how much of that stays.

#### Python

```python
for clip in ["self_correction.wav", "filler.wav"]:
    print(clip)
    for preset in ["light", "clean"]:
        res = dictate(clip, language_code="en-IN",
                      style={"preset": preset})
        print(f"  {preset:>5}: {res.text}")
```

#### JavaScript

```javascript
for (const clip of ["self_correction.wav", "filler.wav"]) {
  console.log(clip);
  for (const preset of ["light", "clean"]) {
    const res = await dictate(clip, { language_code: "en-IN", style: { preset } });
    console.log(`  ${preset.padStart(5)}: ${res.text}`);
  }
}
```

**`Output`**

```text title="Output" wordWrap
self_correction.wav
  light: Let's meet on Tuesday. No, sorry, Wednesday at the main office.
  clean: Let's meet on Wednesday at the main office.
filler.wav
  light: Um, so I was, I was thinking that we could, you know, like maybe go there tomorrow and, and see the place.
  clean: So I was thinking that we could maybe go there tomorrow and see the place.
```

| Preset            | What it does                                                                              | Use it for                                                   |
| ----------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `clean` (default) | Removes fillers and repeated words. Keeps only the corrected version of a self-correction | Text a person sends: a message, a note, an email body        |
| `light`           | Keeps every word. Adds punctuation, fixes names                                           | A record where every word counts: a call log, captions       |
| `none`            | No finishing step and no model call                                                       | You show the raw output, or finish the text in your own code |

`clean` does not rewrite, and it cannot fix what speech recognition heard wrong.

## Bullets, English, rupees and times

**Use it when:** you need a different layout, language or number format. A rule is a plain sentence in `style.rules`, and several rules can share one string, one sentence each.

### Lists and translation

A Tamil to-do note, as bullets, as a checklist, and translated:

#### Python

```python
BULLETS = (
    "Put each task on its own line, "
    'as a bullet that starts with "- ".'
)
rules = {
    "bullets": BULLETS,
    "checkbox": (
        "Write each task on its own line, "
        'starting with "[ ] ".'
    ),
    "in English": "Translate the text into English. " + BULLETS,
}
for name, rule in rules.items():
    res = dictate("tasks_ta.wav", language_code="ta-IN",
                  mode="codemix", style={"rules": rule})
    print(f"--- {name}\n{res.text}")
```

#### JavaScript

```javascript
const BULLETS = 'Put each task on its own line, as a bullet that starts with "- ".';
const rules = {
  bullets: BULLETS,
  checkbox: 'Write each task on its own line, starting with "[ ] ".',
  "in English": "Translate the text into English. " + BULLETS,
};
for (const [name, rule] of Object.entries(rules)) {
  const res = await dictate("tasks_ta.wav", {
    language_code: "ta-IN",
    mode: "codemix",
    style: { rules: rule },
  });
  console.log(`--- ${name}\n${res.text}`);
}
```

**`Output`**

```text title="Output" wordWrap
--- bullets
- நான் வங்கிக்கு போகணும்
- அப்புறம் அம்மாவுக்கு phone பண்ணணும்
- அதுக்கப்புறம் வெள்ளிக்கிழமை rail ticket book பண்ணணும்.
--- checkbox
[ ] நான் வங்கிக்கு போகணும்
[ ] அப்புறம் அம்மாவுக்கு phone பண்ணணும்
[ ] அதுக்கப்புறம் வெள்ளிக்கிழமை rail ticket book பண்ணணும்.
--- in English
- 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.
```

### Money and times

English amounts already come in Indian digit grouping (1,25,000). A rule adds the sign and changes the clock:

#### Python

```python
RUPEE = (
    "Write money amounts as the ₹ sign and digits with Indian "
    "digit grouping, for example ₹1,25,000. Write no currency "
    "word after the amount."
)
H24 = "Write times in 24-hour format, for example 15:30."

CASES = [("no rule", None), ("₹ + 24-hour", RUPEE + " " + H24)]
for name, rules in CASES:
    style = {"rules": rules} if rules else {}
    res = dictate("money.wav", language_code="en-IN", style=style)
    print(f"{name:>12}: {res.text}")
```

#### JavaScript

```javascript
const RUPEE =
  "Write money amounts as the ₹ sign and digits with Indian digit grouping, " +
  "for example ₹1,25,000. Write no currency word after the amount.";
const H24 = "Write times in 24-hour format, for example 15:30.";

const CASES = [
  ["no rule", null],
  ["₹ + 24-hour", `${RUPEE} ${H24}`],
];
for (const [name, rules] of CASES) {
  const style = rules ? { rules } : undefined;
  const res = await dictate("money.wav", { language_code: "en-IN", style });
  console.log(`${name.padStart(12)}: ${res.text}`);
}
```

**`Output`**

```text title="Output" wordWrap
     no rule: Please transfer 1,25,000 rupees to Ravi by the 5th of December. The call with the bank is at 3:30 in the afternoon and the second one is at 9:15 at night.
 ₹ + 24-hour: Please transfer ₹1,25,000 to Ravi by the 5th of December. The call with the bank is at 15:30 in the afternoon and the second one is at 21:15 at night.
```

Number words can stay as words in Telugu and Tamil. Add `Write every number as digits.` to get digits.

### What a rule cannot do

> **Warning**
>
> A rule cannot add content: an email, a greeting, a summary or a shorter text. The words stay as the
> person said them, so an app can paste `text` as the user's own words. Use `output_rules` for those.

#### Python

```python
rule = "Write it as an email, with a greeting and a sign-off."
res = dictate("invoice.wav", language_code="en-IN",
              style={"rules": rule})
print(res.text)
```

#### JavaScript

```javascript
const rule = "Write it as an email, with a greeting and a sign-off.";
const res = await dictate("invoice.wav", {
  language_code: "en-IN",
  style: { rules: rule },
});
console.log(res.text);
```

**`Output`**

```text title="Output" wordWrap
The invoice for October is ready and I will send it to you by Friday. Let me know if the amount looks wrong.
```

| Do                                                                                                  | Why                                            |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Name the change with a verb: "Translate the text into English."                                     | A bare word such as "English." is not a change |
| Say what the result looks like: `Put each task on its own line, as a bullet that starts with "- ".` | Gives the exact marker your app needs          |
| Choose the script with `mode` first                                                                 | `mode=translit` gives Roman Hindi with no rule |
| Put new content in `output_rules`                                                                   | `style.rules` cannot add it                    |

## Names your way: vocabulary

**Use it when:** product, customer or medicine names must come out with your spelling. Speech recognition cannot know that your company is "Velqora" and a customer spells her name "Vyshnavi".

#### Python

```python
VOCAB = [
    {"word": "Velqora"},
    {"word": "Velqora Fiber"},
    {"word": "Vyshnavi Raghunathan"},
]

res = dictate("support_note.wav", language_code="en-IN")
print("no list:   ", res.text)
res = dictate("support_note.wav", language_code="en-IN",
              vocabulary=VOCAB)
print("vocabulary:", res.text)
fixes(res)
```

#### JavaScript

```javascript
const VOCAB = [
  { word: "Velqora" },
  { word: "Velqora Fiber" },
  { word: "Vyshnavi Raghunathan" },
];

let res = await dictate("support_note.wav", { language_code: "en-IN" });
console.log("no list:   ", res.text);
res = await dictate("support_note.wav", { language_code: "en-IN", vocabulary: VOCAB });
console.log("vocabulary:", res.text);
fixes(res);
```

**`Output`**

```text title="Output" wordWrap
no list:    Hi, this is Meera from Belkora Support. I spoke to Vaishnavi Raghunathan about her Belkora fiber connection. Her router has shown a red light since Tuesday, so I raised a ticket and asked the field team to visit tomorrow morning.
vocabulary: Hi, this is Mira from Velqora Support. I spoke to Vyshnavi Raghunathan about her Velqora Fiber connection. Her router has shown a red light since Tuesday, so I raised a ticket and asked the field team to visit tomorrow morning.
  'Belkora' -> 'Velqora' (vocabulary)
  'Vaishnavi Raghunathan' -> 'Vyshnavi Raghunathan' (vocabulary)
  'Belkora fiber' -> 'Velqora Fiber' (vocabulary)
```

`corrections` lists each change, so your app can show the user what changed. If recognition keeps writing a name wrong in the same way, copy that spelling from `transcript` into `sounds_like`:

**`sounds_like`**

```json title="sounds_like"
{"word": "Taxoryn", "sounds_like": ["Taxorin"]}
```

> **Warning**
>
> **Trap 1: a look-alike that was not said.** If the list has a spelling variant of a name that was said,
> Dictate uses the listed spelling, even when recognition had it right. Here the list has "Draxiva" and
> "Harprit", but the speaker said "Draxivo" and "Harpreet".

#### Python

```python
# Look-alike spellings of two names that were said correctly.
vocab = [
    {"word": "Draxiva Logistics"},
    {"word": "Harprit Sodhi"},
    {"word": "Taxoryn"},
]
res = dictate("billing_hi.wav", language_code="hi-IN",
              mode="codemix", vocabulary=vocab)
print(res.text)
fixes(res)
```

#### JavaScript

```javascript
// Look-alike spellings of two names that were said correctly.
const vocab = [
  { word: "Draxiva Logistics" },
  { word: "Harprit Sodhi" },
  { word: "Taxoryn" },
];
const res = await dictate("billing_hi.wav", {
  language_code: "hi-IN",
  mode: "codemix",
  vocabulary: vocab,
});
console.log(res.text);
fixes(res);
```

**`Output`**

```text title="Output" wordWrap
Draxiva Logistics का इस महीने का Taxoryn invoice अभी तक नहीं गया है। Accounts में Harprit Sodhi से बात करो और कल तक भेज दो वरना late fee लगेगी।
  'Draxivo Logistics' -> 'Draxiva Logistics' (vocabulary)
  'taxorin' -> 'Taxoryn' (vocabulary)
  'Harpreet Sodhi' -> 'Harprit Sodhi' (vocabulary)
```

> **Warning**
>
> **Trap 2: the whole catalogue.** A catalogue of 300 customer names in `vocabulary` fixed none of the three
> names in the support note (0 of 3 in each of 4 runs). The same three names alone fixed all of them
> (3 of 3 in each of 4 runs).

| Do                                                                             | Why                                             |
| ------------------------------------------------------------------------------ | ----------------------------------------------- |
| Send the names of this recording: this customer, this patient, this ticket     | A short list works much better than a large one |
| Write `word` exactly as it must appear in `text`, in the script of your `mode` | Every fix uses the listed spelling              |
| List only the right spelling, not variants                                     | A wrong variant can replace a right name        |
| Read `corrections`                                                             | Every change is listed, the wrong ones too      |

`vocabulary` corrects words that recognition wrote. It cannot bring back a word that recognition lost.

## Names from a document: reference

**Use it when:** the names are already in a record you have (a meeting agenda, a CRM record, a prescription). Send it as it is, and Dictate takes the terms from it and uses them like a vocabulary. No list to build.

#### Python

```python
AGENDA = """Orvinta launch sync, Friday
Attendees: Tejaswini Kulkarni (design), Farhan Siddiqui (payments)
Agenda: 1. Onboarding screens
        2. Plivora payment integration
        3. Beta date
Products: Orvinta, Orvinta Lite, Orvinta Max
Payment partner: Plivora checkout"""

clip = "review_meeting.wav"
res = dictate(clip, language_code="hi-IN", mode="codemix")
print("no reference:", res.text)
res = dictate(clip, language_code="hi-IN", mode="codemix",
              context={"reference": AGENDA})
print("reference:   ", res.text)
fixes(res)
```

#### JavaScript

```javascript
const AGENDA = `Orvinta launch sync, Friday
Attendees: Tejaswini Kulkarni (design), Farhan Siddiqui (payments)
Agenda: 1. Onboarding screens
        2. Plivora payment integration
        3. Beta date
Products: Orvinta, Orvinta Lite, Orvinta Max
Payment partner: Plivora checkout`;

const clip = "review_meeting.wav";
let res = await dictate(clip, { language_code: "hi-IN", mode: "codemix" });
console.log("no reference:", res.text);
res = await dictate(clip, {
  language_code: "hi-IN",
  mode: "codemix",
  context: { reference: AGENDA },
});
console.log("reference:   ", res.text);
fixes(res);
```

**`Output`**

```text title="Output" wordWrap
no reference: आज के review में तीन चीजें हैं। पहले Aurvinta Lite का pricing, फिर Plivora checkout के bugs और आखिर में Farhan Siddiqui का demo। Tejaswini Kulkarni design की updates देंगी।
reference:    आज के review में तीन चीजें हैं। पहले Orvinta Lite का pricing, फिर Plivora checkout के bugs और आखिर में Farhan Siddiqui का demo। Tejaswini Kulkarni design की updates देंगी।
  'Aurvinta' -> 'Orvinta' (reference)
  'Aurvinta Lite' -> 'Orvinta Lite' (reference)
```

|               | `vocabulary`                 | `context.reference`                   |
| ------------- | ---------------------------- | ------------------------------------- |
| What you send | A list of names              | Any document, up to 50,000 characters |
| Best for      | The names that must be right | Names that are already in a document  |
| `sounds_like` | Yes                          | No                                    |

You can send both. When a term is in both, the `vocabulary` entry wins.

### The situation: context.text

`context.text` tells the model what the recording is: "A support call about a broadband outage." Use it to describe the situation in a sentence or two.

> **Note**
>
> It can sometimes change how a name is spelled, but it is not reliable: the same text fixed a name in one run
> and not in the next, and the change is not listed in `corrections`. Put names that must be right in
> `vocabulary` or `context.reference`.

#### Python

```python
situation = (
    "A support agent's note about a Velqora Fiber broadband "
    "customer, Vyshnavi Raghunathan. The agent works for "
    "Velqora support."
)
res = dictate("support_note.wav", language_code="en-IN",
              context={"text": situation})
print(res.text)
fixes(res)
```

#### JavaScript

```javascript
const situation =
  "A support agent's note about a Velqora Fiber broadband " +
  "customer, Vyshnavi Raghunathan. The agent works for Velqora support.";
const res = await dictate("support_note.wav", {
  language_code: "en-IN",
  context: { text: situation },
});
console.log(res.text);
fixes(res);
```

**`Output`**

```text title="Output" wordWrap
Hi, this is Mira from Belkora Support. I spoke to Vaishnavi Raghunathan about her Belkora fiber connection. Her router has shown a red light since Tuesday, so I raised a ticket and asked the field team to visit tomorrow morning.
  (no corrections)
```

## JSON, summaries and answers: output rules

**Use it when:** you need something new from the whole recording: JSON for a form, a summary, answers, a reply draft. You get it in `output.text`, next to the normal `text`. The output can only use what was said.

### A sales call into a CRM record

Describe every key: its type, what it holds, and what to write when it was not said.

#### Python

```python
CRM = """Return only one JSON object with exactly these keys, and
no other text. Use null for a value that was not said.
{
  "buyer_name": string | null,    // full name, in English letters
  "buyer_city": string | null,    // city, in English
  "buyer_phone": string | null,   // phone number, digits only
  "buyer_email": string | null,   // email address, as said
  "product": string | null,       // what the buyer wants, with size
  "quantity": number | null,      // how many units
  "unit_price_inr": number | null // price of one unit, in rupees
}"""
res = dictate("sales_call.wav", language_code="hi-IN",
              output_rules=CRM)
record = json.loads(res.output.text)  # a string: parse it
print(json.dumps(record, indent=2, ensure_ascii=False))
total = record["quantity"] * record["unit_price_inr"]
print("order total (computed in code): ₹", total)
```

#### JavaScript

```javascript
const CRM = `Return only one JSON object with exactly these keys, and
no other text. Use null for a value that was not said.
{
  "buyer_name": string | null,    // full name, in English letters
  "buyer_city": string | null,    // city, in English
  "buyer_phone": string | null,   // phone number, digits only
  "buyer_email": string | null,   // email address, as said
  "product": string | null,       // what the buyer wants, with size
  "quantity": number | null,      // how many units
  "unit_price_inr": number | null // price of one unit, in rupees
}`;
const res = await dictate("sales_call.wav", {
  language_code: "hi-IN",
  output_rules: CRM,
});
const record = JSON.parse(res.output.text); // a string: parse it
console.log(JSON.stringify(record, null, 2));
const total = record.quantity * record.unit_price_inr;
console.log("order total (computed in code): ₹", total);
```

**`Output`**

```text title="Output" wordWrap
{
  "buyer_name": "Sunita Kulkarni",
  "buyer_city": "Nashik",
  "buyer_phone": "9822041735",
  "buyer_email": null,
  "product": "water tanks of 1000 liters",
  "quantity": 40,
  "unit_price_inr": 6800
}
order total (computed in code): ₹ 272000
```

### Answers to set questions

Give a way out for questions the call does not answer:

#### Python

```python
QUESTIONS = """Answer each question on its own numbered line, in
English, in one short sentence. If the call does not answer a
question, write "Not mentioned".
1. Which city is the buyer from?
2. How many tanks does the buyer want?
3. Did the buyer ask for a discount?"""
res = dictate("sales_call.wav", language_code="hi-IN",
              output_rules=QUESTIONS)
print(res.output.text)
```

#### JavaScript

```javascript
const QUESTIONS = `Answer each question on its own numbered line, in
English, in one short sentence. If the call does not answer a
question, write "Not mentioned".
1. Which city is the buyer from?
2. How many tanks does the buyer want?
3. Did the buyer ask for a discount?`;
const res = await dictate("sales_call.wav", {
  language_code: "hi-IN",
  output_rules: QUESTIONS,
});
console.log(res.output.text);
```

**`Output`**

```text title="Output" wordWrap
1. The buyer is from Nashik.
2. The buyer wants 40 tanks.
3. Not mentioned.
```

| Do                                                                                                      | Why                                                                  |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Describe every key: type (`string \| null`, `number \| null`), what it holds                            | A bare JSON shape gets keys wrong more often                         |
| Say what to write when a value was not said (`null`, "Not mentioned")                                   | Otherwise the model may invent a value                               |
| For Indian-language audio, write "Write every value in English" at the top, or "in English" in each key | With no language named, the values come back in the speaker's script |
| Name the language of a summary: "in English"                                                            | Otherwise it can follow the clip                                     |
| Ask for one output per request                                                                          | Several outputs in one request can mix up                            |
| Do sums in your own code                                                                                | The model's sums are not reliable                                    |
| Parse `output.text` yourself                                                                            | It is a string. In JavaScript, use `JSON.parse(res.output.text)`     |

The output can only be as right as the text. A name that `vocabulary` fixed in `text` has the same spelling in `output`.

## Long recordings: jobs

**Use it when:** the recording is longer than 30 s, up to 1 hour. Upload it, poll every 5 s, read `result.output.text`, then delete the job.

* Upload compressed audio (MP3, M4A, Opus). Files of about 100 MB or more are refused, so pass `audio_url` for a large file.
* Set a generous timeout for the upload: `SarvamAI(..., timeout=600)` in Python, or `timeoutInSeconds: 600` in JavaScript. For callbacks and `audio_url`, see [Transcribe long recordings](/api/api-guides-tutorials/dictate/how-to/long-recordings).
* Each POST is a new, billed job. Do not send it again without a reason.

#### Python

```python
import time


def run_job(path, **fields):
    """Upload a job, wait for it, delete it, return the result."""
    with open(path, "rb") as f:
        created = client.dictate.jobs.create(file=f, **fields)
    job_id = created.job_id
    while True:
        time.sleep(5)  # poll every 5 s or more
        job = client.dictate.jobs.get(job_id=job_id)
        if job.job_state in ("Completed", "Failed"):
            break
    # Results are kept for 7 days. Delete the job when you are done.
    client.dictate.jobs.delete(job_id=job_id)
    if job.job_state == "Failed":
        raise RuntimeError(f"{job.error.code}: {job.error.message}")
    return job.result


MINUTES = """Return only one JSON object, and no other text:
{
  "summary": string,       // what was decided, in English
  "decisions": [string],   // each decision, one short sentence
  "action_items": [
    {
      "owner": string | null, // who will do it, as named
      "task": string,         // what they will do
      "due": string | null    // when it is due, as said
    }
  ]
}
Use only what was said. Use [] for a list with nothing in it."""

result = run_job("weekly_meeting.mp3", language_code="en-IN",
                 output_rules=MINUTES)
minutes = json.loads(result.output.text)
print("Summary:", minutes["summary"])
for a in minutes["action_items"]:
    owner = a["owner"] or "(no owner)"
    due = a["due"] or "not said"
    print(f"Action: {owner}: {a['task']} (due: {due})")
```

#### JavaScript

```javascript
async function runJob(path, fields) {
  const created = await client.dictate.jobs.create({
    file: fs.createReadStream(path),
    ...fields,
  });
  let job;
  do {
    // poll every 5 s or more
  await new Promise((resolve) => setTimeout(resolve, 5000));
    job = await client.dictate.jobs.get(created.job_id);
  } while (job.job_state !== "Completed" && job.job_state !== "Failed");
  // Results are kept for 7 days. Delete the job when you are done.
  await client.dictate.jobs.delete(created.job_id);
  if (job.job_state === "Failed") {
    throw new Error(`${job.error?.code}: ${job.error?.message}`);
  }
  return job.result;
}

const MINUTES = `Return only one JSON object, and no other text:
{
  "summary": string,       // what was decided, in English
  "decisions": [string],   // each decision, one short sentence
  "action_items": [
    {
      "owner": string | null, // who will do it, as named
      "task": string,         // what they will do
      "due": string | null    // when it is due, as said
    }
  ]
}
Use only what was said. Use [] for a list with nothing in it.`;

const result = await runJob("weekly_meeting.mp3", {
  language_code: "en-IN",
  output_rules: MINUTES,
});
const minutes = JSON.parse(result.output.text);
console.log("Summary:", minutes.summary);
for (const a of minutes.action_items) {
  const owner = a.owner ?? "(no owner)";
  const due = a.due ?? "not said";
  console.log(`Action: ${owner}: ${a.task} (due: ${due})`);
}
```

**`Output`**

```text title="Output" wordWrap
Summary: The team reviewed the Koramangala store launch, confirming the launch date, a backup stock plan, hiring needs, the event budget, and training plan deadlines.
Action: Rohan: tell the landlord in writing about the launch date (due: today)
Action: not mentioned: call the customs agent to find out what form they need and update the group (due: tomorrow morning)
Action: Amit: send 2 candidate profiles (due: Tuesday)
Action: not mentioned: send a breakdown if more than ₹75,000 is needed for the launch event (due: Friday)
Action: Aditya: share the training plan (due: next Monday)
```

For a callback instead of polling, pass `callback={"url": ..., "auth_token": ...}` to `jobs.create`. See [Create Job](/api-reference/dictate/create-job).

> **Note**
>
> The owner of a task is the weakest field in minutes. When two people speak in turn, the model can pick the
> wrong one, or write the text "not mentioned" instead of `null`. Check this field in your app.

## Live dictation: the socket

**Use it when:** the app shows partial text while the user speaks, then one finished text after each pause.

#### Connect

Call `client.dictate_streaming.connect(...)`. The first message is `session.begin`.

#### Configure (optional)

Call `update_config` with `output_rules`, if you need an output at the end.

#### Send audio

`send_audio` with base64 audio: 16 kHz, mono, 16-bit, at most 1 s per message (0.5 s with `stream_type=fast`), at about real-time speed.

#### Show the text

Show each `transcript.partial` as a live preview. Replace the turn with `dictation.final` after each pause.

#### End the session

Call `end` and read until `session.end`. `output.final` comes before it.

#### Python

```python
import asyncio, base64, os, wave
from sarvamai import AsyncSarvamAI
from sarvamai.types import DictateAudioInput, DictateConfigUpdate, DictateEnd

aclient = AsyncSarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
CHUNK = 3200  # 100 ms of 16 kHz, 16-bit mono audio
RULES = (
    'List the action items from this note as bullets that '
    'start with "- ". For each, write the owner, the task and '
    'the due date, as said. Write "None" if there are none.'
)


async def live(path):
    with wave.open(path) as w:    # 16 kHz, mono, 16-bit WAV
        pcm = w.readframes(w.getnframes())
    async with aclient.dictate_streaming.connect(
        language_code="en-IN", encoding="linear16", sample_rate="16000"
    ) as ws:
        async def send_audio():
            await ws.update_config(DictateConfigUpdate(output_rules=RULES))
            for i in range(0, len(pcm), CHUNK):
                chunk = base64.b64encode(pcm[i:i + CHUNK]).decode()
                await ws.send_audio(DictateAudioInput(audio=chunk))
                await asyncio.sleep(CHUNK / 32000)  # real time
            await ws.end(DictateEnd())

        sender = asyncio.create_task(send_audio())
        partials = 0
        async for m in ws:
            if m.event == "session.begin":
                print("connected:", m.event)
            elif m.event == "transcript.partial":
                partials += 1  # show these as a live preview
            elif m.event == "dictation.final":
                print(f"turn {m.utterance_idx}: {m.text}")
            elif m.event == "output.final":
                print("output:\n" + (m.text or "(none)"))
            elif m.event == "error":
                print("error:", m.code, m.message)
            elif m.event == "session.end":
                print(f"{partials} partials, {m.total_utterances} turn(s), "
                      f"billed {m.usage.audio_duration_s} s")
                break
        await sender


asyncio.run(live("live_note.wav"))
```

#### JavaScript

```javascript
const CHUNK = 3200; // 100 ms of 16 kHz, 16-bit mono audio
const RULES =
  'List the action items from this note as bullets that start with "- ". ' +
  "For each, write the owner, the task and the due date, as said. " +
  'Write "None" if there are none.';

// A 16 kHz, mono, 16-bit WAV: skip the 44-byte header to get raw samples.
const pcm = fs.readFileSync("live_note.wav").subarray(44);

const socket = await client.dictateStreaming.connect({
  language_code: "en-IN",
  encoding: "linear16",
  sample_rate: "16000",
  "Api-Subscription-Key": process.env.SARVAM_API_KEY,
});

let partials = 0;
const done = new Promise((resolve) => {
  socket.on("message", (m) => {
    if (m.event === "session.begin") {
      console.log("connected:", m.event);
    } else if (m.event === "transcript.partial") {
      partials += 1; // show these as a live preview
    } else if (m.event === "dictation.final") {
      console.log(`turn ${m.utterance_idx}: ${m.text}`);
    } else if (m.event === "output.final") {
      console.log("output:\n" + (m.text || "(none)"));
    } else if (m.event === "error") {
      console.log("error:", m.code, m.message);
    } else if (m.event === "session.end") {
      const billed = m.usage.audio_duration_s;
      console.log(`${partials} partials, ${m.total_utterances} turn(s), billed ${billed} s`);
      resolve();
    }
  });
});

await socket.waitForOpen();
socket.updateConfig({ event: "config.update", output_rules: RULES });
for (let i = 0; i < pcm.length; i += CHUNK) {
  const chunk = pcm.subarray(i, i + CHUNK).toString("base64");
  socket.sendAudio({ event: "audio_input", audio: chunk });
  await new Promise((r) => setTimeout(r, (CHUNK / 32000) * 1000)); // real time
}
socket.end({ event: "end" });
await done;
socket.close();
```

**`Output`**

```text title="Output" wordWrap
connected: session.begin
turn 0: Note for the team, our order from Nilga Exports is stuck at the Chennai port. Neha will call the customs agent tomorrow at 10. If Nilga Exports cannot send the form by Friday, we open the store with 200 units. Rohan, please send the updated budget to Kriya by Monday.
output:
- Neha, call the customs agent, tomorrow at 10
- Rohan, send the updated budget to Kriya, by Monday
130 partials, 1 turn(s), billed 14.362 s
```

* To add a name in the middle of a session, call `update_config` with `vocabulary`. It applies from the next turn that ends, so it needs a pause between turns.
* For push-to-talk, connect with `endpointing=manual`. Each press is one turn, and only the pressed audio is billed.
* Always call `end` and read until `session.end`, or you lose the last turn and the output.
* Open the socket from your server, not from a browser. The SDK sends your key as a header, which a browser socket cannot do.
* **JavaScript on Node.js 22 and later:** run the script with `node --no-experimental-websocket`, or the socket is refused with `403` (the built-in WebSocket cannot send the key header). See [Live dictation](/api/api-guides-tutorials/dictate/how-to/live-dictation).

## Cheat sheet

| You want                                    | Send                                                                                                                                   |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| A chat message in Hinglish or Tanglish      | `mode=codemix`                                                                                                                         |
| One script, for a document or search        | `mode=transcribe` (default)                                                                                                            |
| Latin letters only                          | `mode=translit`                                                                                                                        |
| An exact record, numbers as words           | `mode=verbatim`                                                                                                                        |
| Every word kept, with punctuation           | `style.preset=light`                                                                                                                   |
| Bullets, a checklist, one sentence per line | `style.rules`                                                                                                                          |
| The text in English                         | `style.rules`: `Translate the text into English.`                                                                                      |
| Names right                                 | `vocabulary` with the names of this recording                                                                                          |
| Names from a document you have              | `context.reference`                                                                                                                    |
| JSON, a summary, answers, a reply           | `output_rules`                                                                                                                         |
| A file longer than 30 s                     | A job                                                                                                                                  |
| Live words while the user speaks            | The socket                                                                                                                             |
| Text that must not change without notice    | `model=dictate-v1-2026-11-04` or `model=dictate-v1-2026-11-05`. The alias `dictate-v1` moves to a newer snapshot after 30 days' notice |

Check in every response: `degraded` (`null` means the finishing step ran), `corrections` (what names changed), and `output.degraded` when you send `output_rules`.

## When something looks wrong

Find the group that matches what you see, then the row.

### Text and names

| You see                                          | Cause                                                                      | Do this                                                                                       |
| ------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `degraded` is set and `text` equals `transcript` | The finishing step failed or timed out. It is not billed                   | Send it again if you need the finished text                                                   |
| A name is misspelled                             | It is not in `vocabulary`, or `word` is in another script than the `mode`  | Add it in the script of the output. Add the wrong spelling from `transcript` as `sounds_like` |
| A different listed name was written              | A look-alike in your list                                                  | Remove names that will not be said in this recording                                          |
| No name is fixed                                 | The list is too long                                                       | Send only the names of this recording                                                         |
| `400` with "is also listed for" in the message   | Two vocabulary entries list the same `sounds_like`. Letter case is ignored | List each misheard form under one word                                                        |
| A rule in `style.rules` did nothing              | It asked for new content, or it was a bare word                            | Move new content to `output_rules`. Write the rule with a verb                                |
| English words come in Devanagari or Tamil script | The default `mode` is `transcribe`                                         | Send `mode=codemix`                                                                           |
| JSON values come in an Indian script             | No language named                                                          | Write "Write every value in English" at the top                                               |

### Language and audio

| You see                                   | Cause                                                                                                                    | Do this                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| The whole text is in the wrong script     | `language_code` does not match the audio (this is not an error), or you sent it in the query string, where it is ignored | Send the right code as a form field, or `auto` |
| A clip returns `200` with an empty `text` | The clip has no speech, only noise. This is not an error                                                                 | Skip empty text                                |

### Requests and limits

| You see                                      | Cause                                         | Do this                                                 |
| -------------------------------------------- | --------------------------------------------- | ------------------------------------------------------- |
| A request gets `307` to an `http://` address | A trailing slash in the path (`/v2/dictate/`) | Use the path exactly as written, with no trailing slash |
| HTTP 429                                     | The key's rate limit. Polls count             | The SDK retries by itself. Poll every 5 s               |
| HTTP 413                                     | The body is too large at the gateway          | Clip: up to 10,000,000 bytes. Job: use `audio_url`      |

### Jobs

| You see                                    | Cause                                                                         | Do this                                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| A job is `Failed` with `invalid_audio_url` | The host name of `audio_url` points to a private address, or does not resolve | Use a public `https` URL. `localhost` and private IP addresses are refused at create with `400` |
| A job is `Failed` with `invalid_audio`     | The file is not readable audio. A job finds this when it runs, not at create  | Check the file. A clip returns `400` for the same file                                          |

### Live socket

| You see                                                       | Cause                                                                   | Do this                                                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| A socket gives wrong text, and the billed seconds are doubled | `sample_rate` does not match the audio                                  | Set `sample_rate` to the real rate (`16000` or `8000`). Send raw samples |
| A socket closes with `1011` and `keepalive ping timeout`      | Your client stopped reading, so it stopped answering the server's pings | Read messages in their own task, and do not block it on slow work        |
| A socket turn has empty `text` and `degraded` is `null`       | A short noise opened a turn                                             | Skip empty turns                                                         |
| `CERTIFICATE_VERIFY_FAILED` on the socket on macOS            | The Python build has no CA file                                         | `pip install certifi`, then set `SSL_CERT_FILE=$(python -m certifi)`     |

## Limits to keep in mind

* **Speech recognition comes first.** No rule or preset fixes a word it heard wrong, so use `vocabulary` for the words you know.
* **Do sums yourself.** Do arithmetic in your own code, and check task owners in meeting minutes.
* **Results vary a little between runs.** Check the text before you depend on it.

[Limitations](/api/api-guides-tutorials/dictate/limitations) has the full list of what Dictate does not do, and its limits.

## Next steps

#### [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.

#### [Dictate a Clip](/api-reference/dictate/clip)

Every field of the clip route, with samples in curl, Python and TypeScript.

#### [Create Job](/api-reference/dictate/create-job)

Recordings up to 1 hour, with callbacks and polling.

#### [WebSocket](/api-reference/dictate/ws)

Live dictation: every message, error and close code.

#### [Authentication](/api-reference/authentication)

Get and use your API key.