REST transcription - Gnani AI Documentation

Speech to Text (REST)

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file=@example-file \
  --form language_code=hi-IN

import requests

url = "https://api.vachana.ai/stt/v3"

files = { "audio_file": ("example-file", open("example-file", "rb")) }
payload = { "language_code": "hi-IN" }
headers = {"X-API-Key-ID": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('audio_file', '<string>');
form.append('language_code', 'hi-IN');

const options = {method: 'POST', headers: {'X-API-Key-ID': '<api-key>'}};

options.body = form;

fetch('https://api.vachana.ai/stt/v3', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "5c1f0a52-6d62-4e0b-9a38-2f2b8a8f7a10",
  "transcript": "मेरा खाता नंबर 12345 है",
  "model": "prisma-v3.0",
  "detected_language_code": "hi-IN",
  "processing_time": 0.62,
  "end_to_end_latency": 0.71
}

POST

stt

Speech to Text (REST)

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file=@example-file \
  --form language_code=hi-IN

import requests

url = "https://api.vachana.ai/stt/v3"

files = { "audio_file": ("example-file", open("example-file", "rb")) }
payload = { "language_code": "hi-IN" }
headers = {"X-API-Key-ID": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('audio_file', '<string>');
form.append('language_code', 'hi-IN');

const options = {method: 'POST', headers: {'X-API-Key-ID': '<api-key>'}};

options.body = form;

fetch('https://api.vachana.ai/stt/v3', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "5c1f0a52-6d62-4e0b-9a38-2f2b8a8f7a10",
  "transcript": "मेरा खाता नंबर 12345 है",
  "model": "prisma-v3.0",
  "detected_language_code": "hi-IN",
  "processing_time": 0.62,
  "end_to_end_latency": 0.71
}

Overview

The REST endpoint transcribes an audio file in a single synchronous HTTP request and returns the transcript immediately. It is best suited for short, pre-recorded audio clips.

Use case	Recommended endpoint
Short clips ≤ 30 s	This endpoint
Live microphone / real-time audio	STT Realtime (WebSocket)
Large files or bulk jobs	STT Batch

Endpoint

POST https://api.vachana.ai/stt/v3
Content-Type: multipart/form-data

Authentication

Pass your API key in the request header.

Header	Type	Required	Description
`X-API-Key-ID`	`string`	Yes	Your Gnani API key. Obtain one from the Gnani APIs dashboard.
`X-API-Request-ID`	`string`	No	Your correlation id, echoed as `request_id`. Generated if omitted.

Request parameters

All parameters are sent as multipart/form-data fields.

file

required

Audio file to transcribe. Supported formats: WAV, MP3, OGG, FLAC, AAC, M4A. Maximum duration: 30 seconds.

string

Model to use. Send prisma-v3.0 for Prisma v3.0. Leave it out to use Prisma v2.5, the default model (the response reports it as prisma-v2.5).

string

required

A language code from Supported Languages. Prisma v2.5 accepts one language. Prisma v3.0 also accepts indic-auto, or a comma-separated list of 1–4 languages, for example hi-IN,en-IN. The model listens for the languages you send first, and the transcript follows the language actually spoken. They are hints, not a lock. See Language detection. Required, except with format=transliterate on prisma-v3.0, where it is optional and defaults to indic-auto.

enum

default:"verbatim"

verbatim — raw spoken-form output. transcribe — enables Inverse Text Normalization (ITN): numbers, currency, dates, and phone numbers are written in their conventional form. See ITN below. codemix (prisma-v3.0 only) keeps English words in Latin script and mostly spells numbers as words. transliterate (prisma-v3.0 only) writes the whole transcript in Latin letters, for example तो ठीक है becomes to theek hai; see Romanised output. With prisma-v3.0, the default when format is omitted depends on the request; see Output styles.

boolean

default:"false"

When format=transcribe, set true to render digits in the native script of the target language (e.g. ₹५,००० instead of ₹5,000 for Hindi). Has no effect when format=verbatim. No effect on prisma-v3.0 for this endpoint.

string

prisma-v3.0: words or short phrases to favour, as a JSON array (["खाता","HDFC Bank"]) or comma-separated, up to 200. See Context.

string

prisma-v3.0: what the recording is about. Any non-empty text, up to 1,600 characters (no minimum).

string

prisma-v3.0: the transcript of the clip just before this one. Any non-empty text (no minimum); the last 600 characters are kept. Applies to the first part of the audio only.

string

prisma-v3.0: a JSON array or comma-separated names, 1–4.

You can send any combination of keyterms, topic, previous_text and speaker_names, from none to all four. A value outside its limit returns 400 INVALID_CONTEXT. See Context.

boolean

default:"false"

Set to true to enable post-transcription find-and-replace. When enabled, all patterns listed in substitution_map are replaced in the final transcript text after recognition and ITN. Has no effect when false (default) — the substitution_map field is ignored entirely.

string

A JSON-encoded list of substitution rules applied to the transcript after recognition and ITN. Only evaluated when enable_substitution=true. Maximum 10 rules.Each rule is an object with two fields:

Field	Type	Description
`patterns`	`string[]`	One or more strings to find. Matching is case-insensitive and respects Unicode word boundaries, so `"ok"` matches `"OK"` and `"Ok"` but not `"okay"`.
`replacement`	`string`	The string to substitute for every matched pattern in this rule.

[
  {"patterns": ["okay", "ok", "alright"], "replacement": "acknowledged"},
  {"patterns": ["rupees", "rs"],           "replacement": "INR"}
]

Rules are applied in a single pass — there is no risk of one replacement being re-matched by a later rule. Longer phrases take priority over shorter ones (e.g. "New Delhi" matches before "Delhi").

Substitution runs on the final client-visible transcript only. Billing records always carry the original raw transcript regardless of this setting.

string

Prisma v2.5. Words to boost during recognition — brand names, product names, or other terms the model tends to miss. Up to 100 words, as a JSON array (["EMI","Prisma"]) or comma-separated (EMI,Prisma). Each entry must be a single word of letters only (no spaces, digits, punctuation, or symbols). Only takes effect together with a positive bias_score. See Word Boosting below. On prisma-v3.0, bias_list is the older name of keyterms and is used only when keyterms is not sent.

number

Prisma v2.5 only; ignored by prisma-v3.0. Boost strength for bias_list. One of 0.0, 0.5, 1.0, 1.5, 2.0. 0.0 or omitted turns boosting off.

Response

200 — Success

{
  "success": true,
  "request_id": "5c1f0a52-6d62-4e0b-9a38-2f2b8a8f7a10",
  "transcript": "मेरा खाता नंबर 12345 है",
  "model": "prisma-v3.0",
  "detected_language_code": "hi-IN",
  "processing_time": 0.62,
  "end_to_end_latency": 0.71
}

Field	When	Description
`success`	always	`true`
`request_id`	always	your `X-API-Request-ID`, or a generated UUID
`transcript`	always	the text; `""` when there is no speech. A string, never a dictionary for `prisma-v3.0`. With `format=transliterate` the whole transcript is in Latin letters. That format works only with `prisma-v3.0`, not Prisma v2.5.
`model`	always†	`prisma-v3.0` (v2.5 returns `prisma-v2.5`)
`detected_language_code`	Prisma v3.0: every request with text, except `format=transliterate`	locale judged from the script of the transcript, for every request; absent when there is nothing to judge, such as an empty transcript. Not returned with `format=transliterate`. See Reading `detected_language_code`.
`truncated`	only when it happens	`true` when the model hit its token limit and the transcript was cut short. Retry with shorter audio. It is left out when the transcript is complete, so `truncated: false` is never returned.
`processing_time`	always†	seconds spent on the request after upload was parsed
`end_to_end_latency`	always†	seconds since the request arrived — includes your upload time
`output.literal`	Prisma v2.5	the transcript before inverse text normalization (ITN); the same as `transcript` when ITN changes nothing

†Audio shorter than 0.1 s returns {"success": true, "request_id": "…", "transcript": ""} with no model or timings. An empty transcript is not an error. Prisma v2.5 returns model as prisma-v2.5 and the output.literal field:

{
  "success": true,
  "request_id": "req_abc123",
  "transcript": "नमस्ते, आप कैसे हैं?",
  "model": "prisma-v2.5",
  "processing_time": 0.14,
  "end_to_end_latency": 0.17,
  "output": {
    "literal": "नमस्ते, आप कैसे हैं?"
  }
}

A transcript that was cut short carries truncated:

{
  "success": true,
  "request_id": "5c1f0a52-6d62-4e0b-9a38-2f2b8a8f7a10",
  "transcript": "…",
  "model": "prisma-v3.0",
  "truncated": true,
  "processing_time": 1.4,
  "end_to_end_latency": 1.5
}

Error responses

Speech-to-Text (REST) errors use this envelope:

{"success": false, "error": {"type": "INVALID_CONTEXT", "message": "…"}}

The HTTP status is the reliable signal; branch on error.type. These responses use a different shape: validation errors such as a missing language_code or audio_file (422 with {"detail": [...]}), the 504 on Prisma v3.0, authentication and rate-limit errors, Batch errors, Text-to-Speech and Voice Cloning errors and streaming error messages.

Prisma v3.0

HTTP	`error.type`	When	Example message
422	none (body is `{"detail": [...]}`, not the envelope)	`language_code` missing or empty (not for `format=transliterate`, where it is optional)	`{"detail":[{"type":"missing","loc":["body","language_code"],"msg":"Field required","input":null}]}`
422	none (body is `{"detail": [...]}`)	`audio_file` is missing	`{"detail":[{"type":"missing","loc":["body","audio_file"],"msg":"Field required","input":null}]}`
400	`INVALID_LANGUAGE_CODE`	A code the service does not recognise (for example `xx-XX`, `hi` or lowercase `hi-in`), or more than 4 languages	`Unsupported languages: xx-XX. Supported languages: as-IN, bn-IN, en-IN, …` or `At most 4 languages are allowed, got 5: hi-IN, en-IN, ta-IN, te-IN, kn-IN.`
400	`MODEL_UNSUPPORTED_LANGUAGE`	A locale the model does not cover (for example `as-IN`)	`prisma-v3.0 does not support languages: as-IN. Supported languages for this model: bn-IN, en-IN, …`
400	`INVALID_MODEL`	`model` is not a known model name	`Invalid model 'foo'. Supported models: prisma-v2.5, prisma-v3.0`
400	`INVALID_FORMAT`	`format` is not `verbatim`, `transcribe`, `codemix` or `transliterate` (or `codemix` or `transliterate` on another model)	`Invalid format. Supported values are: verbatim, transcribe, codemix, transliterate, or omit format.`
400	`INVALID_CONTEXT`	Out-of-range value, `<\|` / `\|>` in a value, or too many keyterms or speaker names	`topic must be at most 1600 characters (got 1601)`
400	`EMPTY_AUDIO`	Zero-byte upload	`Empty audio file received`
400	`UNSUPPORTED_AUDIO_FORMAT`	File-name extension not supported	`Unsupported audio format. Supported formats: …`
400	`AUDIO_CONVERSION_ERROR`	The file could not be decoded	`Failed to convert audio format: …`
400	`MAX_AUDIO_DURATION_EXCEEDED`	Audio longer than the limit	`Audio duration exceeds maximum allowed duration of 30 seconds`
500	`TRANSCRIPTION_FAILED`	Transcription failed	`Speech recognition service failed to transcribe audio. Please try again.`
500	`INTERNAL_SERVER_ERROR`	Unexpected failure	`Internal server error occurred. Please try again later.`
504	`UPSTREAM_TIMEOUT` (field `code`)	Transcription did not finish in time	See the body below

The 504 body is not the envelope:

{
  "error": "Gateway Timeout",
  "code": "UPSTREAM_TIMEOUT",
  "message": "The speech-to-text model failed to respond within the allocated 5000ms limit."
}

The 504 bounds the transcription step only, so a request can take longer end to end and still succeed.

Prisma v2.5

Prisma v2.5 returns the same error.type values as Prisma v3.0 where they apply (see the Prisma v3.0 table for the audio errors EMPTY_AUDIO, UNSUPPORTED_AUDIO_FORMAT, AUDIO_CONVERSION_ERROR and MAX_AUDIO_DURATION_EXCEEDED, and for INTERNAL_SERVER_ERROR). These are the ones specific to v2.5:

HTTP	`error.type`	When	Example message
400	`INVALID_FORMAT`	`format` is not `verbatim` or `transcribe`	`Invalid format. Supported values are: verbatim, transcribe, or omit format.`
400	`INVALID_LANGUAGE_CODE`	An unsupported code, or more than one language	`Unsupported languages: xx-XX. Supported languages: …`
400	`INVALID_MODEL`	`model` is not a known model name (`prisma-v2.5` is accepted, and so is leaving `model` out)	`Invalid model 'foo'. Supported models: prisma-v2.5, prisma-v3.0`
422	none (body is `{"detail": [...]}`)	`language_code` or `audio_file` is missing, or `bias_score` is not a number	`{"detail":[{"type":"missing","loc":["body","language_code"],"msg":"Field required","input":null}]}`
500	`INTERNAL_SERVER_ERROR`	For example, `substitution_map` is not valid JSON	`Internal server error occurred. Please try again later.`

Invalid bias_list input, or a numeric bias_score that is not an allowed value, is skipped and the request succeeds.

Authentication and rate limits

Authentication and rate-limit errors do not use the success / error envelope. They look like this:

{"detail": {"error_code": "RATE_LIMITED", "message": "Only 1 active request is allowed at a time. Wait for your current request to finish before sending another.", "status_code": 429}}

HTTP	`detail.error_code`	Typical cause
`401`	`MISSING_API_KEY`	The `X-API-Key-ID` header is missing or empty.
`401`	`INVALID_API_KEY`	The key is not valid (`"message": "Unauthorized"`).
`402`	not verified	Insufficient credit
`403`	`SCOPE_NOT_ALLOWED`	The key lacks the scope for this service (for example `Service 'STT' not in allowed scopes`).
`429`	`RATE_LIMITED`	Too many requests for your account. For example, an account limited to one active request at a time returns `429` while a request is still running. The response has no `Retry-After` header: wait a moment, then retry with backoff.

The same shapes are returned by REST, Batch, Text-to-Speech, Voice Cloning and the Realtime handshake (as an HTTP response before the WebSocket opens). See Error Reference for streaming, Batch and retry guidance.

Code example

The examples below are grouped by language and model version. Each block is a complete request you can copy. The model form field selects the version: send prisma-v3.0 for Prisma v3.0; leave it out for Prisma v2.5.

cURL — Prisma v3.0

cURL — Auto-detect the language

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <API_KEY>' \
  --form audio_file=@recording.wav \
  --form model=prisma-v3.0 \
  --form language_code=indic-auto

cURL — One language and output style

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <API_KEY>' \
  --form audio_file=@recording.wav \
  --form model=prisma-v3.0 \
  --form language_code=hi-IN \
  --form format=transcribe

cURL — Romanised output (Latin letters)

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <API_KEY>' \
  --form audio_file=@recording.wav \
  --form model=prisma-v3.0 \
  --form format=transliterate

cURL — Keyterms and topic

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <API_KEY>' \
  --form audio_file=@recording.wav \
  --form model=prisma-v3.0 \
  --form language_code=hi-IN \
  --form 'topic=Quarterly review of retail banking dues and card collections' \
  --form 'keyterms=["खाता","नंबर","HDFC Bank"]'

cURL — Several options in one request

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <API_KEY>' \
  --header 'X-API-Request-ID: my-trace-123' \
  --form audio_file=@recording.wav \
  --form model=prisma-v3.0 \
  --form language_code=indic-auto \
  --form format=codemix \
  --form 'topic=Quarterly review of retail banking dues and card collections' \
  --form 'keyterms=["खाता","नंबर","HDFC Bank"]' \
  --form enable_substitution=true \
  --form 'substitution_map=[{"patterns":["एचडीएफसी"],"replacement":"HDFC"}]'

You can add previous_text and speaker_names to the same request. Any combination of the four context fields is accepted.

Python — Prisma v3.0

Python — Auto-detect the language

import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={"model": "prisma-v3.0", "language_code": "indic-auto"},
        timeout=60,
    )
body = r.json()
print(body["transcript"], body.get("detected_language_code"))

Python — One language and output style

import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={"model": "prisma-v3.0", "language_code": "hi-IN", "format": "transcribe"},
        timeout=60,
    )
print(r.json()["transcript"])

Python — Romanised output (Latin letters)

import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={"model": "prisma-v3.0", "format": "transliterate"},   # language_code is optional
        timeout=60,
    )
print(r.json()["transcript"])

Python — Keyterms and topic

import json
import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={
            "model": "prisma-v3.0",
            "language_code": "hi-IN",
            "topic": "Quarterly review of retail banking dues and card collections",
            "keyterms": json.dumps(["खाता", "नंबर", "HDFC Bank"], ensure_ascii=False),
        },
        timeout=60,
    )
print(r.json()["transcript"])

Python — Several options in one request

import json
import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>", "X-API-Request-ID": "my-trace-123"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={
            "model": "prisma-v3.0",
            "language_code": "indic-auto",
            "format": "codemix",
            "topic": "Quarterly review of retail banking dues and card collections",
            "keyterms": json.dumps(["खाता", "नंबर", "HDFC Bank"], ensure_ascii=False),
            "enable_substitution": "true",
            "substitution_map": json.dumps(
                [{"patterns": ["एचडीएफसी"], "replacement": "HDFC"}], ensure_ascii=False
            ),
        },
        timeout=60,
    )
print(r.json())

cURL — Prisma v2.5

cURL — Transcribe with native numerals

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file='@recording.wav' \
  --form language_code=hi-IN \
  --form format=transcribe \
  --form itn_native_numerals=true

cURL — Find-and-replace

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file='@recording.wav' \
  --form language_code=en-IN \
  --form enable_substitution=true \
  --form 'substitution_map=[{"patterns":["okay","ok"],"replacement":"acknowledged"},{"patterns":["rupees","rs"],"replacement":"INR"}]'

cURL — Word boosting

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file='@recording.wav' \
  --form language_code=hi-IN \
  --form format=verbatim \
  --form 'bias_list=["Prisma","EMI"]' \
  --form bias_score=1.0

Python — Prisma v2.5

Python — Transcribe with native numerals

import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={"language_code": "hi-IN", "format": "transcribe", "itn_native_numerals": "true"},
        timeout=60,
    )
print(r.json()["transcript"])

Python — Find-and-replace

import json
import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={
            "language_code": "en-IN",
            "enable_substitution": "true",
            "substitution_map": json.dumps(
                [
                    {"patterns": ["okay", "ok"], "replacement": "acknowledged"},
                    {"patterns": ["rupees", "rs"], "replacement": "INR"},
                ]
            ),
        },
        timeout=60,
    )
print(r.json()["transcript"])

Python — Word boosting

import json
import requests

with open("recording.wav", "rb") as f:
    r = requests.post(
        "https://api.vachana.ai/stt/v3",
        headers={"X-API-Key-ID": "<API_KEY>"},
        files={"audio_file": ("recording.wav", f, "audio/wav")},
        data={
            "language_code": "hi-IN",
            "format": "verbatim",
            "bias_list": json.dumps(["Prisma", "EMI"]),
            "bias_score": "1.0",
        },
        timeout=60,
    )
print(r.json()["transcript"])

Python SDK

from gnani.stt import GnaniSTTClient

client = GnaniSTTClient(api_key="your-api-key")

result = client.transcribe("recording.wav", language_code="hi-IN")
print(result["transcript"])

Python SDK

The official Python SDK handles multipart construction, authentication headers, and retries automatically.

Installation

pip install gnani-vachana

Requires Python 3.10+.

Authentication

The client requires an api_key credential. You can pass it directly or load it from environment variables.

from gnani.stt import GnaniSTTClient

client = GnaniSTTClient(
    api_key="your-api-key"
)

export GNANI_API_KEY="your-api-key"

from gnani.stt import GnaniSTTClient

# Picks up credentials from environment automatically
client = GnaniSTTClient()

Transcribe audio

result = client.transcribe("recording.wav", language_code="hi-IN")
print(result["transcript"])

with open("recording.wav", "rb") as f:
    result = client.transcribe(f, language_code="hi-IN")
print(result["transcript"])

with open("recording.wav", "rb") as f:
    audio_bytes = f.read()

result = client.transcribe(audio_bytes, language_code="hi-IN")
print(result["transcript"])

Custom request ID

Pass a request_id to correlate SDK calls with your own logs or support tickets.

result = client.transcribe(
    "call.flac",
    language_code="hi-IN",
    request_id="my-trace-123",
)

Error handling

from gnani.stt import (
    AuthenticationError,
    InvalidAudioError,
    APIError,
)

try:
    result = client.transcribe("audio.wav", language_code="hi-IN")
    print(result["transcript"])
except AuthenticationError:
    print("Invalid credentials — check your organization_id, api_key, and user_id.")
except InvalidAudioError as e:
    print(f"Bad audio file: {e}")
except APIError as e:
    print(f"API error {e.status_code}: {e}")

Supported languages

Both models support the same 10 languages.

Language	Code	Native Script	Example
Bengali	`bn-IN`	Bengali (বাংলা)	“আমি ভাত খাই”
English	`en-IN`		“I am going to the market”
Gujarati	`gu-IN`	Gujarati (ગુજરાતી)	“હું બજાર જાઉં છું”
Hindi	`hi-IN`	Devanagari (हिन्दी)	“मैं बाज़ार जा रहा हूँ”
Kannada	`kn-IN`	Kannada (ಕನ್ನಡ)	“ನಾನು ಮಾರುಕಟ್ಟೆಗೆ ಹೋಗುತ್ತೇನೆ”
Malayalam	`ml-IN`	Malayalam (മലയാളം)	“ഞാൻ ചന്തയിലേക്ക് പോകുന്നു”
Marathi	`mr-IN`	Devanagari (मराठी)	“मी बाजारात जातोय”
Punjabi	`pa-IN`	Gurmukhi (ਪੰਜਾਬੀ)	“ਮੈਂ ਬਾਜ਼ਾਰ ਜਾ ਰਿਹਾ ਹਾਂ”
Tamil	`ta-IN`	Tamil (தமிழ்)	“நான் சந்தைக்கு செல்கிறேன்”
Telugu	`te-IN`	Telugu (తెలుగు)	“నేను మార్కెట్‌కి వెళ్తున్నాను”

indic-auto (Prisma v3.0 only). Send language_code=indic-auto to let the model identify the language itself. It is not a language: the reply carries the language it heard in detected_language_code. See Language detection.

Inverse text normalization (ITN)

This section describes Prisma v2.5. On Prisma v3.0 the model formats numbers itself when format=transcribe; see Output styles. ITN converts the spoken-form output of the ASR engine into the conventional written form a reader expects — numbers become digits, currency gets the ₹ symbol, dates are formatted, and phone numbers are compacted — all in one pass, immediately after transcription. How to enable: Set format=transcribe in the request body.

What ITN normalizes

1 — Cardinal & ordinal numbers

Whole numbers and positional ranks are formatted using Indian comma grouping (groups of 2 after the first 3 digits).

Spoken input (ASR)	Written output (ITN)	Rule
दो हज़ार	2,000	Indian comma grouping
पाँच लाख बीस हज़ार	5,20,000	Lakh-scale grouping
उन्नीस सौ चौरानवे	1,994	Hundred-base year form
five lakh	5,00,000	English lakh convention
पहला / twenty first	1st / 21st	Ordinal suffix

2 — Currency & money

All Indian currency expressions — including paise fractions and lakh/crore scales — are formatted with the ₹ symbol and Indian comma grouping.

Spoken input (ASR)	Written output (ITN)	Rule
पाँच सौ रुपये	₹500	₹ + amount
तीन रुपये पचास पैसे	₹3.50	₹ + rupees.paise
दस लाख रुपये	₹10,00,000	₹ + lakh grouping
I need five thousand rupees	₹5,000	English India pipeline

3 — Dates

Spoken input (ASR)	Written output (ITN)	Rule
बीस जनवरी दो हज़ार पच्चीस	20 जनवरी 2025	DD Month YYYY (hi)
fifteenth january twenty twenty five	15th January 2025	Ordinal Month YYYY (en)

4 — Times

Indian time-of-day words (सुबह, दोपहर, शाम, रात) automatically map to 24-hour HH:MM output.

Spoken input (ASR)	Written output (ITN)	Rule
सुबह पाँच बजे	सुबह 05:00	सुबह = AM
शाम पाँच बजे	शाम 17:00	शाम = evening (16–20 h)
रात के दस बजे	रात 22:00	रात = night (20–24 h)
meeting at five fifteen in the evening	meeting 17:15 in the evening	en — 24-hour

5 — Phone numbers & PIN codes

Digit streams are concatenated into compact numeric strings. 10-digit streams → mobile number; 6-digit streams → PIN. Repeat prefixes (double/डबल, triple/ट्रिपल) are expanded.

Spoken input (ASR)	Written output (ITN)	Rule
नौ आठ सात छह पाँच चार तीन दो एक शून्य	9876543210	10 digits → phone
एक एक शून्य शून्य शून्य एक	110001	6 digits → PIN
डबल आठ नौ शून्य एक दो तीन चार पाँच छह	8890123456	double prefix
one two three four five six	123456	English digit words

6 — Mixed & code-mixed utterances

A single sentence may contain multiple entity types or blend Hindi and English. ITN handles all in one pass, normalizing each entity independently.

Spoken input (ASR)	Written output (ITN)
कल थ्री फिफ्टी पीएम को पाँच सौ रुपये transfer करना है	कल 15:50 को ₹500 transfer करना है

Native script digits — `itn_native_numerals`

By default, ITN outputs Western Arabic digits (0–9) regardless of language. Set itn_native_numerals=true to render digits in the native script of the target language.

Language	Spoken input	`false` (default)	`true` — native script
Hindi `hi-IN`	पाँच हज़ार रुपये	₹5,000	₹५,०००
English `en-IN`	five thousand rupees	₹5,000	₹5,000 (Latin — no change)

What ITN does not change

ITN intentionally preserves idiomatic and ambiguous phrases to avoid incorrect normalization.

दो तीन (meaning a few) stays as text, not 2 or 3
कर दो / ले दो (imperative verbs) are kept as words, not treated as cardinal 2

If a word or phrase is unchanged in the output, treat it as a failure only when the input was unambiguously a numeric entity.

Find-and-replace (substitution)

Find-and-replace applies on both models and runs after transcription. After transcription (and after ITN, if enabled), the API can apply a custom set of find-and-replace rules to the transcript. Use this to:

Normalise domain-specific terms (“rs” → “INR”, “ok” → “acknowledged”)
Replace competitor names, internal codes, or product shortforms
Standardise phrases that the model consistently transcribes differently from your expected output

How to enable

Set enable_substitution=true and pass your rules as a JSON string in substitution_map.

Rule format

[
  {"patterns": ["find1", "find2", "find3"], "replacement": "replacement1"},
  {"patterns": ["find4"],                   "replacement": "replacement2"}
]

Up to 10 rules per request.
Each rule can list any number of patterns that all map to the same replacement.
Matching is case-insensitive ("ok" matches "OK", "Ok", "ok").
Matching respects Unicode word boundaries — "ok" does not match inside "okay".
Longer phrases always match before shorter ones — "New Delhi" is tried before "Delhi".
Rules are applied in a single pass with no cascading — a replacement is never re-matched by another rule.

Example

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file='@call.wav' \
  --form language_code=en-IN \
  --form format=transcribe \
  --form enable_substitution=true \
  --form 'substitution_map=[
    {"patterns": ["okay", "ok", "alright"], "replacement": "acknowledged"},
    {"patterns": ["rupees", "rs"],           "replacement": "INR"},
    {"patterns": ["New Delhi", "Delhi"],     "replacement": "NCR office"}
  ]'

Original transcript (from ASR + ITN)	After substitution
`ok, the payment of ₹500 rupees is done`	`acknowledged, the payment of ₹500 INR is done`
`alright, please contact the Delhi branch`	`acknowledged, please contact the NCR office branch`

Substitution runs on the final client-visible transcript only. Billing and analytics records always carry the original raw transcript regardless of this setting.

Word boosting (`bias_list`)

This section describes Prisma v2.5. For Prisma v3.0 use keyterms; see Context. Word boosting nudges the recognizer toward specific words so they are more likely to be transcribed correctly — useful for brand names, product names, and domain terms that are otherwise misheard. It influences recognition itself; it is not a find-and-replace (see Find-and-Replace for that).

How to use

Send both fields together:

Field	Description
`bias_list`	Up to 100 words, as a JSON array or comma-separated string.
`bias_score`	`0.0`, `0.5`, `1.0`, `1.5` or `2.0`.

`bias_score`	Effect
`0.0`	Off (same as omitting it)
`0.5`	Light nudge
`1.0`	Typical starting point
`1.5`	Stronger
`2.0`	Maximum

Start at 1.0 and raise only if a word is still missed — stronger boosting can make the model favour a listed word where it wasn’t spoken.

Word rules

Each entry is one word. Phrases such as "loan number" are not allowed.
Letters only — English letters or letters in the supported Indian scripts. No digits (HDFC2), punctuation (HDFC-EMI), or symbols (@brand).
Casing does not matter.
Maximum 100 words; any beyond that are dropped.
Use format=verbatim. Boost words are spoken-form tokens, so digit strings and normalized numbers won’t work.
Use a JSON array if you’d rather not worry about commas; both formats are accepted.

Invalid input does not return an error. If any entry breaks the rules (or bias_score is not an allowed value), the whole list is ignored and the audio is transcribed without boosting, still returning 200. If boosting seems to have no effect, check your list first.

When it applies

Boosting applies when language_code is a specific language such as hi-IN or en-IN, and you use Prisma v2.5, the default model (omit model). Batch STT has its own bias_list and bias_score settings; see Word boosting on Batch. The response format is unchanged; boosted words are not echoed back.

Example

curl --request POST \
  --url https://api.vachana.ai/stt/v3 \
  --header 'X-API-Key-ID: <api-key>' \
  --form audio_file='@call.wav' \
  --form language_code=en-IN \
  --form format=verbatim \
  --form bias_list=Prisma,Vachana \
  --form bias_score=1.0

Behaviour notes (Prisma v3.0)

One transcript. On v3.0 transcript is always a string, never a dictionary.
An empty transcript is not an error. Log it; do not treat it as a failure.
truncated: true means the model hit its token limit and the transcript is incomplete. Retry with shorter audio or split the recording. The field is only present when this happens.
Context can lower accuracy — test with and without it.
end_to_end_latency includes your upload; processing_time does not.
Results for identical audio can differ by a borderline word; cache results if you need stable output.
Very short utterances (under about a second) are the least reliable. Silence is detected first, and a clip with no speech returns an empty transcript.

Authorizations

X-API-Key-ID

string

header

required

API key for authentication. Sign up in Vachana to get the API Key.

Body

multipart/form-data

audio_file

file

required

Audio file to transcribe. Supported formats - WAV, MP3, OGG, FLAC, AAC, M4A. Maximum duration - 30 seconds.

language_code

string

required

Language code for transcription. Required for both models. Use one of the supported language codes. Prisma v2.5 accepts one language.

Prisma v3.0 accepts indic-auto (let the model identify the language), or a comma-separated list of 1-4 languages, for example hi-IN,en-IN. The model listens for the languages you send first, and the transcript follows the language actually spoken. They are hints, not a lock.

With format=transliterate on prisma-v3.0 this field is optional and defaults to indic-auto.

Supported values: bn-IN, en-IN, gu-IN, hi-IN, kn-IN, ml-IN, mr-IN, pa-IN, ta-IN, te-IN

Example:

"hi-IN"

model

enum<string>

Model to use. Send prisma-v3.0 for Prisma v3.0. Leave it out to use Prisma v2.5, the default model (the response reports it as prisma-v2.5).

Available options:

prisma-v3.0

Example:

"prisma-v3.0"

format

enum<string>

default:verbatim

Output format for the transcript.

verbatim (default on Prisma v2.5) — Returns the raw spoken-form transcript as recognised by the ASR engine. No post-processing is applied.
transcribe — Enables Inverse Text Normalization (ITN). Spoken numeric expressions, currency, dates, times, and phone numbers are automatically converted to their written form (e.g. "five thousand rupees" → "₹5,000").
codemix (prisma-v3.0 only) — English words stay in Latin script; numbers mostly stay as spoken words.
transliterate (prisma-v3.0 only) — the whole transcript is written in Latin letters (for example तो ठीक है becomes to theek hai); numbers are spelled out as words. language_code becomes optional. detected_language_code is not returned.

With prisma-v3.0, the default when format is omitted depends on the request. See Output styles.

Available options:

verbatim,

transcribe,

codemix,

transliterate

Example:

"transcribe"

itn_native_numerals

boolean

default:false

When format=transcribe, set to true to render digits in the native script of the target language instead of Western Arabic digits (0–9).

For example, with hi-IN: "पाँच हज़ार रुपये" → "₹५,०००" instead of "₹5,000".

Has no effect when format=verbatim. No effect on prisma-v3.0 for this endpoint.

Example:

true

keyterms

string

prisma-v3.0: words or short phrases to favour, as a JSON array or comma-separated, up to 200. Can be combined with topic, previous_text and speaker_names.

Example:

"[\"खाता\",\"HDFC Bank\"]"

topic

string

prisma-v3.0: what the recording is about. Any non-empty text, up to 1,600 characters (no minimum).

Maximum string length: 1600

previous_text

string

prisma-v3.0: transcript of the clip just before this one. Any non-empty text (no minimum); the last 600 characters are kept.

speaker_names

string

prisma-v3.0: JSON array or comma-separated names, 1–4.

Example:

"[\"Priya\",\"Rahul\"]"

enable_substitution

boolean

default:false

Set to true to enable post-transcription find-and-replace. All patterns listed in substitution_map are applied to the transcript after recognition and ITN.

When false (default), the substitution_map field is ignored entirely — no performance cost.

Example:

true

substitution_map

string

JSON-encoded list of substitution rules applied to the transcript after recognition and ITN. Only evaluated when enable_substitution=true. Maximum 10 rules.

Each rule must have:

patterns (array of strings) — one or more strings to find. Matching is case-insensitive and respects Unicode word boundaries.
replacement (string) — the string to substitute for every matched pattern in this rule.

Rules are applied in a single pass — no cascading. Longer phrases take priority over shorter ones.

Example value:

[{"patterns":["okay","ok"],"replacement":"acknowledged"},{"patterns":["rupees","rs"],"replacement":"INR"}]

Example:

"[{\"patterns\":[\"okay\",\"ok\"],\"replacement\":\"acknowledged\"},{\"patterns\":[\"rupees\",\"rs\"],\"replacement\":\"INR\"}]"

bias_list

string

Prisma v2.5: words to boost during recognition (word boosting). On prisma-v3.0, bias_list is the older name of keyterms; it is used only when keyterms is not sent. Up to 100 words, sent as a JSON array or a comma-separated string. Each entry must be a single word made of letters only — no spaces, digits, punctuation, or symbols. Must be paired with a positive bias_score.

Use with format=verbatim for best results. Applies to the supported languages with the default model (Prisma v2.5).

An invalid list never fails the request — it is transcribed normally with boosting skipped.

Example:

"[\"Timbre\",\"Prisma\",\"EMI\"]"

bias_score

enum<number>

Prisma v2.5 only; ignored by prisma-v3.0. Boost strength for bias_list. Allowed values: 0.0, 0.5, 1.0, 1.5, 2.0. 0.0 (or omitting it) disables boosting; any other number is ignored and boosting is skipped. A value that is not a number is rejected with 422.

Available options:

0,

0.5,

1,

1.5,

2

Example:

1

Response

Successful transcription

success

boolean

Indicates if the transcription was successful

request_id

string

Your X-API-Request-ID, or a generated id.

output

object

Prisma v2.5 only.

Show child attributes

transcript

string

The transcribed text from the audio. With format=transliterate the whole transcript is in Latin letters. That format works only with prisma-v3.0, not Prisma v2.5.

model

string

Example:

"prisma-v3.0"

detected_language_code

string

Prisma v3.0 only. Locale judged from the script of the transcript, for every request. Absent when there is nothing to judge, such as an empty transcript, and not returned with format=transliterate.

Example:

"hi-IN"

truncated

boolean

Present, and true, only when the model hit its token limit and the transcript was cut short. Left out when the transcript is complete, so false is never returned.

processing_time

number

Seconds spent on the request after the upload was parsed.

end_to_end_latency

number

Seconds since the request arrived. Includes upload time.

​Overview

​Endpoint

​Authentication

​Request parameters

​Response

​200 — Success

​Error responses

​Prisma v3.0

​Prisma v2.5

​Authentication and rate limits

​Code example

​cURL — Prisma v3.0

​Python — Prisma v3.0

​cURL — Prisma v2.5

​Python — Prisma v2.5

​Python SDK

​Installation

​Authentication

​Transcribe audio

​Custom request ID

​Error handling

​Supported languages

​Inverse text normalization (ITN)

​What ITN normalizes

​1 — Cardinal & ordinal numbers

​2 — Currency & money

​3 — Dates

​4 — Times

​5 — Phone numbers & PIN codes

​6 — Mixed & code-mixed utterances

​Native script digits — itn_native_numerals

​What ITN does not change

​Find-and-replace (substitution)

​How to enable

​Rule format

​Example

​Word boosting (bias_list)

​How to use

​Word rules

​When it applies

​Example

​Behaviour notes (Prisma v3.0)

Authorizations

Body

Response

Overview

Endpoint

Authentication

Request parameters

Response

200 — Success

Error responses

Prisma v3.0

Prisma v2.5

Authentication and rate limits

Code example

cURL — Prisma v3.0

Python — Prisma v3.0

cURL — Prisma v2.5

Python — Prisma v2.5

Python SDK

Installation

Authentication

Transcribe audio

Custom request ID

Error handling

Supported languages

Inverse text normalization (ITN)

What ITN normalizes

1 — Cardinal & ordinal numbers

2 — Currency & money

3 — Dates

4 — Times

5 — Phone numbers & PIN codes

6 — Mixed & code-mixed utterances

Native script digits — `itn_native_numerals`

What ITN does not change

Find-and-replace (substitution)

How to enable

Rule format

Example

Word boosting (`bias_list`)

How to use

Word rules

When it applies

Example

Behaviour notes (Prisma v3.0)