Skip to navigation

Transcribe Long Recordings

View as Markdown

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

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)

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.

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",
},
)

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