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

# Transcribe Long Recordings

> Use a Dictate job for a recording up to 1 hour: upload or pass a URL, poll or get a callback, read the result, then delete the job.

A clip is limited to 30 s. For a longer recording, up to 1 hour, create a **job**. The flow is always:
create the job, wait for it, read the result, delete the job. Results are kept for 7 days.

## Upload a file and wait

#### Python

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

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

with open("weekly_meeting.mp3", "rb") as f:
    created = client.dictate.jobs.create(
        file=f,
        language_code="en-IN",
        output_rules=(
            'Return only JSON: '
            '{"summary": string, "decisions": [string]}'
        ),
    )

while True:
    time.sleep(5)  # poll every 5 s or more
    job = client.dictate.jobs.get(job_id=created.job_id)
    if job.job_state in ("Completed", "Failed"):
        break

if job.job_state == "Completed":
    print(job.result.text)
    print(job.result.output.text)
else:
    print(job.error.code, job.error.message)

# 204: the result and the inputs are gone
client.dictate.jobs.delete(job_id=created.job_id)
```

#### JavaScript

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

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

const created = await client.dictate.jobs.create({
  file: fs.createReadStream("weekly_meeting.mp3"),
  language_code: "en-IN",
  output_rules:
    'Return only JSON: {"summary": string, "decisions": [string]}',
});

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");

if (job.job_state === "Completed") {
  console.log(job.result?.text);
  console.log(job.result?.output?.text);
} else {
  console.log(job.error?.code, job.error?.message);
}

// 204: the result and the inputs are gone
await client.dictate.jobs.delete(created.job_id);
```

## Use a URL, or get a callback

Pass `audio_url` instead of `file` and Dictate downloads the audio. Use it for any file of about 100 MB or more,
which an upload refuses. Pass `callback` and Dictate calls you when the job is `Completed` or `Failed`, so you do
not have to poll.

#### Python

```python
job = client.dictate.jobs.create(
    audio_url="https://example.com/recordings/standup.mp3",
    language_code="en-IN",
    callback={
        "url": "https://hooks.example.com/dictate",
        "auth_token": "a-long-random-secret",
    },
)
```

#### JavaScript

```javascript
const job = await client.dictate.jobs.create({
  audio_url: "https://example.com/recordings/standup.mp3",
  language_code: "en-IN",
  callback: {
    url: "https://hooks.example.com/dictate",
    auth_token: "a-long-random-secret",
  },
});
```

> **Note**
>
> **Check the address early.** `audio_url` and `callback.url` must start with `https://`. Dictate refuses an `http://` URL,
> `localhost`, and a private or loopback IP address such as `https://10.0.0.5/...`, at create with `400`. Any other host
> name is checked when the job runs. A name that points to a private address, or that does not resolve, gives `202`, and the job
> then ends `Failed` with `invalid_audio_url`. A file that cannot be downloaded ends `Failed` with `fetch_failed`. Read
> `error.code` when you poll.

The callback body is only `{"job_id": "...", "job_state": "Completed"}`. It does not hold the result: read it with
`jobs.get`. Check the `X-SARVAM-JOB-CALLBACK-TOKEN` header against your `auth_token`. A callback can arrive more than
once, so make your handler safe to run twice. Dictate retries a failed delivery after 5 s, 30 s, 2 min, 10 min, 30 min
and 1 h.

## Good to know

* Upload compressed audio (MP3, M4A, Opus), and set a long timeout for the upload.
* Each `create` is a new, billed job. Do not send it again without a reason.
* A job that is still running cannot be deleted: `jobs.delete` returns `409` (`conflict_error`), and no call stops a running job. Delete it after it is `Completed` or `Failed`.
* Poll every 5 s or more. Reads count toward your [rate limit](/api/getting-started/pricing#dictate-limits).
* The result has the same fields as a clip, plus `sections` and `segments` with `start_s` and `end_s` times.
* A job that fails has `job_state` of `Failed` and an `error` with a `code` and `message`. Unreadable audio is found only when the job runs: `create` returns `202`, then the job ends `Failed` with `invalid_audio`. Only a clip refuses it up front, with `400`.