Keyterm Prompting | Sarvam API Docs

saaras:v4 only. Keyterms are supported only with model="saaras:v4", on the REST, Batch, and WebSocket streaming APIs (both the legacy /speech-to-text/ws and realtime /speech-to-text-realtime/ws endpoints).

Keyterms help Saaras v4 recognize important names, places, brands, and technical terms that may occur in an audio file, for example:

["Sarvam", "New Delhi", "Vistaar"]

Keyterms bias recognition; they do not guarantee that a term will appear in the transcript.

Rules

Rule	Detail
Model support	Only `model="saaras:v4"`
Format	JSON list of strings under `keyterms`
Max terms	50 distinct keyterms
Max length	64 characters per keyterm
Phrases	Put phrases such as `New Delhi` in one list item
Delimiting	Do not send comma-separated terms in one string
Deprecated fields	Do not use the older `keyterm` or `hotwords` fields

Use mode="codemix" instead of mode="transcribe" when a keyterm such as PhonePe must remain in Latin script, the keyterms format is unchanged across all supported modes. See Choosing the transcription mode below.

Upgrade your SDK before using keyterms. Python: verified on sarvamai>=0.1.33a1 for REST, sarvamai>=0.1.33a3 for speech_to_text_job.create_job(). JavaScript: verified on sarvamai>=1.1.10-alpha.1 for speechToTextJob.createJob(), a fix for REST speechToText.transcribe() has not shipped to npm yet; until it’s released, use the JavaScript Batch example below, or the REST cURL/Python examples.

REST API

REST requests use multipart/form-data. Send keyterms as a JSON-encoded array in one form field.

import os
from sarvamai import SarvamAI
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
response = client.speech_to_text.transcribe(
    file=open("audio.wav", "rb"),
    model="saaras:v4",
    mode="transcribe",
    language_code="hi-IN",
    keyterms=["Sarvam", "New Delhi", "Vistaar"],
)
print(response.transcript)

Omit language_code to use automatic language detection.

Batch API

For batch jobs, keyterms is a normal JSON array inside job_parameters.

job = client.speech_to_text_job.create_job(
    model="saaras:v4",
    mode="transcribe",
    language_code="hi-IN",
    with_diarization=True,
    keyterms=["Sarvam", "New Delhi", "Vistaar"],
)
job.upload_files(file_paths=["interview.wav"])
job.start()
job.wait_until_complete()
job.download_outputs(output_dir="./output")

After creating the job, use the returned job ID to upload the audio, start the job, poll its status, and download the output using the standard Batch API workflow.

Batch with diarization

Add with_diarization. The same keyterms are applied while transcribing every audio chunk in the job, the downloaded result includes the full transcript and, when requested, speaker-attributed entries under diarized_transcript.

job = client.speech_to_text_job.create_job(
    model="saaras:v4",
    mode="transcribe",
    language_code="hi-IN",
    with_diarization=True,
    with_timestamps=True,
    keyterms=["Sarvam", "New Delhi", "Vistaar"],
)

See Enable Speaker Diarization for the full diarization output format.

Streaming WebSockets

Both WebSocket endpoints accept keyterms as a query parameter on the connection URL, sent as a JSON-encoded (and URL-encoded) array:

wss://api.sarvam.ai/speech-to-text/ws?model=saaras:v4&language_code=hi-IN&keyterms=%5B%22Sarvam%22%2C%22New%20Delhi%22%5D
wss://api.sarvam.ai/speech-to-text-realtime/ws?model=saaras:v4&language_code=hi-IN&keyterms=%5B%22Sarvam%22%2C%22New%20Delhi%22%5D

The Python and JavaScript SDK connect() helpers do not expose keyterms yet, so use a raw WebSocket client and append the query parameter yourself:

import asyncio
import base64
import json
import os
import urllib.parse
import websockets
async def transcribe_with_keyterms():
    params = urllib.parse.urlencode({
        "model": "saaras:v4",
        "language_code": "hi-IN",
        "keyterms": json.dumps(["Sarvam", "New Delhi", "Vistaar"]),
    })
    async with websockets.connect(
        f"wss://api.sarvam.ai/speech-to-text/ws?{params}",
        additional_headers={"api-subscription-key": os.environ["SARVAM_API_KEY"]},
    ) as ws:
        audio = base64.b64encode(open("audio.wav", "rb").read()).decode("utf-8")
        await ws.send(json.dumps({
            "audio": audio,
            "encoding": "audio/wav",
            "sample_rate": 16000,
        }))
        print(await ws.recv())
asyncio.run(transcribe_with_keyterms())

Keyterms are set when the connection is opened and apply for the whole session; they cannot be changed mid-stream.

Choosing the transcription mode

The keyterms format is unchanged across all supported modes:

Mode	Behavior
`transcribe`	Native-script transcription; English words use native script
`codemix`	Native-script transcription; English words remain in Latin script
`verbatim`	Speech as spoken, without punctuation
`translit`	Transcription in Latin script
`translate`	English translation

For example, use mode="codemix" instead of mode="transcribe" when a keyterm such as PhonePe must remain in Latin script.

Need help choosing between REST and Batch? See Which API to Use.