Speech-to-Text (Batch)
Use STT Batch to transcribe long recordings or many files asynchronously. Flow: upload audio → start a job → poll until it finishes → download transcripts(or receive them on a webhook).
Table of contents
- How it works
- Before you begin
- Quickstart
- How do I get the transcript text?
- Choose how to send audio
- Recipes
- Configuration
- Limits
- Supported languages
- Supported audio formats
- API reference
- Job statuses
- File statuses
- Webhooks
- Errors
- Common mistakes
- Python example
- Support
How it works
/start.
Before you begin
- An API key from the Gnani APIs dashboard
- Audio in a supported format
- A supported language code
Quickstart (copy-paste)
1. Create the job
201 Created
job_id. Always start with this path (even if the message mentions /v1/jobs/...):
2. Start processing
202 Accepted
3. Poll status
- Poll no faster than every 10 seconds
- For large jobs (100+ files), prefer every 30 seconds
- Stop when status is
COMPLETED,PARTIAL_FAILURE,FAILED,START_FAILED, orCANCELLED
200 OK (in progress)
200 OK (done)
4. Get completed files
This response gives youtranscript_url — not the transcript text yet.
200 OK
5. Download the transcript (full_transcript)
If you are not using webhooks, this is the step that returns the text.
Call transcript_url with a normal HTTP GET. Do not send X-API-Key-ID — the URL is pre-signed.
- Use
full_transcriptfor the complete text - Use
segmentsfor timestamps / speaker labels transcript_urlexpires in 1 hour — re-call/filesfor a fresh URL
How do I get the transcript text?
GET /jobs/{job_id} and GET /jobs/{job_id}/files do not return full_transcript./files only returns transcript_url. You must GET that URL to get the text.
Choose how to send audio
Only these three methods are supported. Authenticated private bucket access (IAM AssumeRole, GCS keys, Azure keys) is not available.
Recipes
Multiple files
201 Created
ZIP upload
201 Created
Public URL
/start, not at create. If every path fails:
Two-speaker diarization
- Send
num_speakerswhenwith_diarizationistrue - Max speakers: 2
- Set
is_multi_channel: trueonly for true multi-channel audio (for example stereo A/B); leavefalsefor mono
Cancel before start
200 OK
Configuration
Inverse Text Normalization (ITN) is not supported for STT Batch.
Limits
Direct upload
ZIP upload
Transcript URL
transcript_url is created when you call GET /jobs/{job_id}/files. Re-call /files for a fresh URL. No API key is needed to download from the URL.
Polling
- Poll
GET /jobs/{job_id}no faster than every 10 seconds - For 100+ file jobs, prefer every 30 seconds
- Stop on a terminal status
Supported languages
Example error —
400 UNSUPPORTED_LANGUAGE
Supported audio formats
.wav · .mp3 · .mp4 · .flac · .ogg · .opus · .m4a · .aac · .webm · .amr
Tone-only or silent audio may be accepted into a job but later fail with Empty transcript after 3 retries. Use real speech.
API reference
Create job — upload / ZIP
Create job — public URL
Start job
409
Get job status
List jobs
Get file results
Without webhooks:
- Call this after the job is terminal
- Take
transcript_urlfor eachCOMPLETEDfile GETthat URL → readfull_transcript
full_transcript itself.
Cancel job
{ "reason": "..." } with Content-Type: application/json.
Job statuses
File statuses
Webhooks
Passcallback_url at create time to receive a POST when the job reaches a terminal state.
The
transcripts array includes full per-file transcript JSON (with full_transcript), so webhook users usually do not need /files + transcript_url.
If you are not using webhooks, see How do I get the transcript text?.
Treat webhooks as best-effort. Polling remains the source of truth.
Sample webhook payload
Errors
Missing API key —401
400
409
404
409
Common mistakes
Python example
Support
Docs feedback: Batch STT docs feedback Last verified: 28 Jul 2026 againsthttps://api.vachana.ai