Batch STT Introduction

Use STT Batch to transcribe long recordings or many files asynchronously. Flow: create a job → start it → poll until it finishes → download transcripts
(or receive them on a webhook).

If you need…	Use
Long files, many files, or offline pipelines	STT Batch (this section)
Short clips (under ~60 seconds), immediate answer	STT REST
Live microphone / streaming audio	STT Realtime

How it works

1. CREATE    POST /stt/v3/batch/jobs
             → 201  job_id   status: CREATED

2. START     POST /stt/v3/batch/jobs/{job_id}/start
             → 202             status: STARTING

3. WAIT      GET  /stt/v3/batch/jobs/{job_id}
             poll every 10s until a terminal status
             (live: STARTING → QUEUED → IN_PROGRESS → COMPLETED)

4. FILES     GET  /stt/v3/batch/jobs/{job_id}/files
             → transcript_url for each completed file

5. DOWNLOAD  GET  <transcript_url>
             → JSON with full_transcript + segments

Important: creating a job does not start transcription. You must call /start.

Interactive API reference

Each endpoint has a Try it playground. Paste your X-API-Key-ID and run live requests from the docs.

Step	Endpoint	Page
1	`POST /stt/v3/batch/jobs`	Create Job
2	`POST /stt/v3/batch/jobs/{job_id}/start`	Start Job
3	`GET /stt/v3/batch/jobs/{job_id}`	Get Job Status
4	`GET /stt/v3/batch/jobs/{job_id}/files`	Get Job Files
—	`GET /stt/v3/batch/jobs`	List Jobs
—	`POST /stt/v3/batch/jobs/{job_id}/cancel`	Cancel Job

Webhook payload examples: Webhooks — samples for job.completed, job.failed, and job.cancelled.

Before you begin

An API key from the Gnani APIs dashboard
Audio with real speech in a supported format
A supported language code

Base URL

https://api.vachana.ai

Auth — send on every Batch API request:

X-API-Key-ID: <YOUR_API_KEY>

Tone-only / silent audio is accepted into a job but fails later with Empty transcript after 3 retries.

How do I get the transcript text?

Option	When to use	What you do
A. Polling (default)	No webhook	Poll job status → `GET /files` → `GET` each `transcript_url` → read `full_transcript`
B. Webhook	You passed `callback_url`	Receive a POST with `transcripts[]` including `full_transcript`

GET /jobs/{job_id} and GET /jobs/{job_id}/files do not return full_transcript.

Quickstart (live-verified)

1. Create

curl --request POST \
  --url https://api.vachana.ai/stt/v3/batch/jobs \
  --header 'X-API-Key-ID: <YOUR_API_KEY>' \
  -F 'config={"model":"gnani-prisma-v2.5","language_code":"en-IN","mode":"transcribe","with_diarization":false,"is_multi_channel":false};type=application/json' \
  -F "files=@./customer_call.wav"

{
  "job_id": "019fa79e-81f9-7a8a-a446-6eff16ddec30",
  "status": "CREATED",
  "total_files_accepted": 1,
  "created_at": "2026-07-28T07:26:50.926489Z",
  "message": "1 file(s) uploaded. Call POST /v1/jobs/{job_id}/start to begin processing."
}

2. Start

curl --request POST \
  --url https://api.vachana.ai/stt/v3/batch/jobs/019fa79e-81f9-7a8a-a446-6eff16ddec30/start \
  --header 'X-API-Key-ID: <YOUR_API_KEY>'

{
  "job_id": "019fa79e-81f9-7a8a-a446-6eff16ddec30",
  "status": "STARTING",
  "message": "Job start accepted. File validation and queueing are running in the background. Poll GET /stt/v3/batch/jobs/{job_id} to track progress."
}

3. Poll until `COMPLETED`

curl --request GET \
  --url https://api.vachana.ai/stt/v3/batch/jobs/019fa79e-81f9-7a8a-a446-6eff16ddec30 \
  --header 'X-API-Key-ID: <YOUR_API_KEY>'

4. Get `transcript_url`, then download text

curl --request GET \
  --url 'https://api.vachana.ai/stt/v3/batch/jobs/019fa79e-81f9-7a8a-a446-6eff16ddec30/files?status=COMPLETED' \
  --header 'X-API-Key-ID: <YOUR_API_KEY>'

curl -L "<transcript_url>"

{
  "full_transcript": "hello how can i help you today i am calling about my recent order number 12345",
  "model": "gnani-prisma-v2.5",
  "language_code": "en-IN",
  "duration_seconds": 6.01
}

Configuration

Field	Type	Required	Default	Description
`model`	string	Yes	—	`"gnani-prisma-v2.5"`
`language_code`	string	Yes	—	See Supported languages
`mode`	string	No	`"transcribe"`	Use `"transcribe"` for now
`with_diarization`	boolean	No	`false`	Enable speaker diarization
`num_speakers`	integer	Yes, if diarization is on	—	Max 2
`is_multi_channel`	boolean	No	`false`	`true` only for true multi-channel audio

Inverse Text Normalization (ITN) is not supported for STT Batch.

Limits

Limits depend on how you send the audio. The size and file-count limits below apply to direct upload only — they do not apply to files fetched from cloud storage.

Every file, whichever way it arrives

Limit	Value
Max audio duration	4 hours per file
Min audio duration	0.1 s per file
Max speech segments detected	5,000 per file

A file longer than 4 hours is rejected with AUDIO_TOO_LONG. Split it first.

Direct upload (`multipart/form-data`)

Limit	Value
Max audio files per job	100
Max size per file	10 MB
Max ZIP compressed size	50 MB
Max ZIP decompressed size	200 MB
Max ZIP compression ratio	50:1

The 100-file limit counts everything in the job, including files expanded out of a ZIP.

Cloud storage (`source.type: "cloud_storage"`)

Limit	Value
Max size per file	No byte limit — bounded by the 4-hour duration cap above
Max download time per file	30 minutes
Max files per job	Not currently capped

The 10 MB limit is for uploads only. Sending a 200 MB recording as a cloud_storage path is fine — what matters is that it is under 4 hours and downloadable within 30 minutes. Uploading that same file through multipart/form-data would be rejected.

A path ending in / is treated as a folder and expands to every supported audio file under that prefix. Because cloud storage jobs are not file-count capped, a broad prefix can enqueue far more audio than you intended — and every file is billed. Point at explicit file paths, or a narrow prefix you have checked.

Results and polling

Limit	Value
`transcript_url` expiry	1 hour (`X-Amz-Expires=3600`)
Poll interval	≥ 10 s (prefer 30 s for 100+ files)

The poll interval is guidance, not an enforced limit — but the API is rate limited, so polling more tightly than this risks 429 responses on your other calls.

Supported languages

Code	Language
`bn-IN`	Bengali (India)
`en-IN`	English (India)
`hi-IN`	Hindi
`kn-IN`	Kannada
`ml-IN`	Malayalam
`mr-IN`	Marathi
`ta-IN`	Tamil
`te-IN`	Telugu

Batch vs REST/Realtime: Gujarati (gu-IN) and Punjabi (pa-IN) are supported on STT REST and STT Realtime but not on Batch STT. Use REST or Realtime for those languages.

Language identification

If you know the language, pass a single code and it is used for the whole file. If you do not, pass up to three codes as a comma-separated list. Each file is then identified as one of exactly those languages and transcribed in it:

"language_code": "hi-IN,en-IN"

Rules:

Maximum three codes. More returns 400 UNSUPPORTED_LANGUAGE.
Every code must be from the table above; one unsupported code rejects the request.
Order matters. The first code is the fallback used when identification is not confident enough to choose.
The decision is made per file, not per segment — a file is transcribed entirely in one language. The resolved language is returned as language_code in the transcript JSON, so it always tells you what the text is actually in.
A single code behaves exactly as before, with no identification step.

Supported audio formats

.wav · .mp3 · .mp4 · .flac · .ogg · .opus · .m4a · .aac · .webm · .amr

Job statuses

Status	Terminal	Meaning
`CREATED`	No	Waiting for `/start`
`STARTING`	No	Setup running
`QUEUED`	No	Files queued
`IN_PROGRESS`	No	Transcription running
`COMPLETED`	Yes	All succeeded
`PARTIAL_FAILURE`	Yes	Mixed results
`FAILED`	Yes	Failed
`START_FAILED`	Yes	Setup failed — see `cancel_reason`
`CANCELLING`	No	Cancel in progress
`CANCELLED`	Yes	Cancelled

Webhooks

Pass callback_url at create time to receive a POST when the job reaches a terminal state.

`event`	Triggered when
`job.completed`	All files succeeded
`job.partial_failure`	Mixed success / failure
`job.failed`	All files failed
`job.cancelled`	Job cancelled

The transcripts array includes full per-file transcript JSON (with full_transcript), so webhook users usually do not need /files + transcript_url. Treat webhooks as best-effort. Polling remains the source of truth.

Sample webhook payload — `job.completed`

{
  "event": "job.completed",
  "job_id": "019fa79e-81f9-7a8a-a446-6eff16ddec30",
  "org_id": "org_acme123",
  "user_id": "user_abc456",
  "status": "COMPLETED",
  "total_files": 1,
  "completed_files": 1,
  "failed_files": 0,
  "cancelled_files": 0,
  "completed_at": "2026-07-28T07:27:24Z",
  "callback_url": "https://yourapp.com/webhooks/stt",
  "transcripts": [
    {
      "file_id": "6f5e3bcd-add2-479c-8883-a9c27b221f10",
      "job_id": "019fa79e-81f9-7a8a-a446-6eff16ddec30",
      "original_path": "customer_call.wav",
      "language_code": "en-IN",
      "duration_seconds": 6.01,
      "model": "gnani-prisma-v2.5",
      "mode": "transcribe",
      "segments": [
        {
          "segment_id": 0,
          "start_time": 0.0,
          "end_time": 0.71,
          "text": "hello",
          "speaker_id": 1,
          "confidence": null,
          "language_detected": null,
          "sentiment": null,
          "emotion": null
        },
        {
          "segment_id": 0,
          "start_time": 0.71,
          "end_time": 2.36,
          "text": "how can i help you today",
          "speaker_id": 2,
          "confidence": null,
          "language_detected": null,
          "sentiment": null,
          "emotion": null
        },
        {
          "segment_id": 0,
          "start_time": 2.36,
          "end_time": 6.01,
          "text": "i am calling about my recent order number 12345",
          "speaker_id": 2,
          "confidence": null,
          "language_detected": null,
          "sentiment": null,
          "emotion": null
        }
      ],
      "full_transcript": "hello how can i help you today i am calling about my recent order number 12345",
      "created_at": "2026-07-28T07:27:24Z"
    }
  ]
}

Sample webhook payload — `job.failed`

{
  "event": "job.failed",
  "job_id": "019fa79b-a07a-7a3e-93bf-4ee73974dfa2",
  "org_id": "org_acme123",
  "user_id": "user_abc456",
  "status": "FAILED",
  "total_files": 1,
  "completed_files": 0,
  "failed_files": 1,
  "cancelled_files": 0,
  "completed_at": "2026-07-28T07:24:32Z",
  "callback_url": "https://yourapp.com/webhooks/stt",
  "transcripts": []
}

Sample webhook payload — `job.cancelled`

{
  "event": "job.cancelled",
  "job_id": "019fa79c-7880-7d05-a528-edc7892ad9ea",
  "org_id": "org_acme123",
  "user_id": "user_abc456",
  "status": "CANCELLED",
  "total_files": 1,
  "completed_files": 0,
  "failed_files": 0,
  "cancelled_files": 1,
  "completed_at": null,
  "callback_url": "https://yourapp.com/webhooks/stt",
  "transcripts": []
}

Common mistakes

Mistake	What happens	Fix
Forgetting `/start`	Job stays `CREATED`	Call Start Job
Expecting `full_transcript` on status/`/files`	Field missing	`GET /files` → then `GET transcript_url`
Using `/v1/jobs/...` from create message	Wrong path	Use `/stt/v3/batch/jobs/{job_id}/start`
Uploading silence / tones	`FAILED` — `Empty transcript after 3 retries`	Use real speech
Invalid public URL	`START_FAILED` / file `SKIPPED`	Use reachable HTTPS URLs
Polling every 1–2 seconds	Wasted calls	Poll every 10s
Expired `transcript_url`	Download fails	Re-call Get Job Files

Support

Docs feedback: Batch STT docs feedback Last verified: 5 August 2026 Live-checked: Create → Start → Poll → Files → Transcript download, List, Cancel, and error codes 401 / 400 / 404 / 409.

​How it works

​Interactive API reference

​Before you begin

​How do I get the transcript text?

​Quickstart (live-verified)

​1. Create

​2. Start

​3. Poll until COMPLETED

​4. Get transcript_url, then download text

​Configuration

​Limits

​Every file, whichever way it arrives

​Direct upload (multipart/form-data)

​Cloud storage (source.type: "cloud_storage")

​Results and polling

​Supported languages

​Language identification

​Supported audio formats

​Job statuses

​Webhooks

​Sample webhook payload — job.completed

​Sample webhook payload — job.failed

​Sample webhook payload — job.cancelled

​Common mistakes

​Support

How it works

Interactive API reference

Before you begin

How do I get the transcript text?

Quickstart (live-verified)

1. Create

2. Start

3. Poll until `COMPLETED`

4. Get `transcript_url`, then download text

Configuration

Limits

Every file, whichever way it arrives

Direct upload (`multipart/form-data`)

Cloud storage (`source.type: "cloud_storage"`)

Results and polling

Supported languages

Language identification

Supported audio formats

Job statuses

Webhooks

Sample webhook payload — `job.completed`

Sample webhook payload — `job.failed`

Sample webhook payload — `job.cancelled`

Common mistakes

Support