Job Lifecycle

create() → not_started

The job row exists and you hold a job_id plus a signed upload_url. Nothing is processing yet.

start() → queued

Starting is idempotent in practice: calling it on a job that is already queued, in_progress, or completed returns without re-queueing.

Processing → in_progress

The job flips to in_progress once processing begins, and stays there for the bulk of the run.

Finished → completed, partial_failure, or failed

Exports are then triggered automatically for the formats in export_options.

Install the SDK and set your key

$
pip install sarvamai
$
export SARVAM_API_KEY="your-key-here"

Reading the key from an environment variable keeps it out of your source code, so you can share the script without sharing your credentials. Generate a key at Key Management.

Set up the client and your inputs

1
import os, time
2
from pathlib import Path
3
from sarvamai import SarvamAI
4
5
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
6
7
media = Path("sample.mp4")
8
target_language_codes = ["hi-IN", "ta-IN"]
9
export_options = ["video", "srt"]

client is the object every call goes through. The three values below it are the only things you would normally change: the file to dub, the languages to dub it into, and the formats you want back. Naming them once here matters, because later steps reuse them to work out exactly what to wait for.

Create the job

1
created = client.dubbing.create(
2
    source_language_code="en-IN",
3
    target_language_codes=target_language_codes,
4
    export_options=export_options,
5
    voice_cloning=True,
6
    num_speakers=1,
7
    job_name=media.name,
8
)
9
job_id = created.data.job_id

This registers the job and reserves somewhere to put your file. Nothing is processing yet and the file has not been sent. What comes back is a job_id, which identifies this job in every later call, and an upload_url, which is a temporary link to upload the file to.

voice_cloning=True keeps each original speaker’s voice, and num_speakers=1 says the source has one person talking. Both are covered in Choose a Voice.

Upload the media, then start the job

1
client.dubbing.upload(created.data.upload_url, media)
2
client.dubbing.start(job_id=job_id)

Uploading sends the file straight to storage rather than through the API, which is why it is a separate call from create. Starting then tells the service the file is in place and work can begin.

Order matters: starting before the file is uploaded leaves the job sitting at queued with nothing to process.

Wait for the dub to finish

1
TERMINAL = {"completed", "partial_failure", "failed", "deleted"}
2
3
deadline = time.monotonic() + 3600
4
while True:
5
    job = client.dubbing.get_live_status(job_id=job_id).data
6
    print(f"{job.progress:>3}%  {job.current_step_label}")
7
8
    if job.status in TERMINAL:
9
        break
10
    if time.monotonic() > deadline:
11
        raise TimeoutError(f"{job_id} did not finish in time")
12
13
    time.sleep(15)

Dubbing takes minutes rather than seconds, so instead of waiting on one long request you ask for the status every 15 seconds until the job stops changing.

The loop exits on any status in TERMINAL, not just completed. That matters for partial_failure, which means some languages finished and others did not — there are still real files to collect, so it counts as done. The deadline is a safety net so the loop cannot run forever.

Stop if the job failed outright

1
if job.status == "failed":
2
    raise RuntimeError(job.error_message or "job failed")

failed is the only terminal status with nothing to collect. Everything else, partial_failure included, has output worth fetching, so the script continues.

Wait for the exported files

1
wanted = {(lang, fmt) for lang in target_language_codes for fmt in export_options}
2
3
deadline = time.monotonic() + 3600
4
while True:
5
    exports = client.dubbing.get_export_status(job_id=job_id, limit=100).data.exports or []
6
    settled = {
7
        (e.target_language, e.export_type)
8
        for e in exports
9
        if e.status in {"completed", "failed"}
10
    }
11
12
    if wanted <= settled:
13
        break
14
    if time.monotonic() > deadline:
15
        raise TimeoutError(f"{job_id} exports did not settle in time")
16
17
    time.sleep(15)

A finished job does not yet mean finished files, because each output is rendered after the dub itself completes. This is a second wait, for the files rather than the dub.

wanted is every combination you asked for: two languages times two formats is four files. The loop keeps polling until each of those has settled, meaning it either completed or failed, so one slow file cannot make you miss the others. limit=100 is deliberate — the default of 5 would not return every entry.

Collect the download links

1
downloads = {
2
    (e.target_language, e.export_type): e.download_url
3
    for e in exports
4
    if e.status == "completed" and not e.is_stale
5
}
6
7
for (lang, fmt), url in sorted(downloads.items()):
8
    print(f"{lang} {fmt}: {url}")

This keeps only the files that actually completed, and skips any marked is_stale, which means the translation was edited after that file was made. The links are signed and valid for roughly 24 hours, so download them now or re-poll export-status later for fresh ones.