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

Limit	Value
Max audio files per job	100
Max file size	10 MB per file
Max ZIP compressed size	50 MB
Max ZIP decompressed size	200 MB
`transcript_url` expiry	1 hour (`X-Amz-Expires=3600`)
Poll interval	≥ 10 s (prefer 30 s for 100+ files)

Supported languages

Code	Language
`bn-BD`	Bengali (Bangladesh)
`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.

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

​Supported languages

​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

Supported languages

Supported audio formats

Job statuses

Webhooks

Sample webhook payload — `job.completed`

Sample webhook payload — `job.failed`

Sample webhook payload — `job.cancelled`

Common mistakes

Support