speech-to-text

语音转文字 — Saaras

聊天内实时转写 → sarvam-mcp（sarvam_tools_stt_*）。此技能 = SDK 代码。

重要

身份验证：使用 api-subscription-key 标头，而不是 Authorization: Bearer。基础 URL：https://api.sarvam.ai（不是 /v1——此前缀仅用于兼容 OpenAI 的聊天端点）

模型

saaras:v3（默认，推荐）——支持 23 种语言、5 种输出模式（transcribe、translate、verbatim、translit、codemix），并可自动检测语言。

saaras:v4（最新）——模式和语言相同，此外还支持全球英语（不只是印度英语）和关键术语提示：在 REST、Batch 或任一 WebSocket 流式端点上，传入 keyterms=["Sarvam", "New Delhi", ...]（最多 50 个术语，每个术语最多 64 个字符），使识别结果倾向于特定领域的名称、品牌和术语。keyterms 仅适用于 saaras:v4——JS 特定注意事项请参阅“注意事项”。

快速开始（Python）

from sarvamai import SarvamAI
client = SarvamAI()

response = client.speech_to_text.transcribe(
    file=open("audio.wav", "rb"),
    model="saaras:v3",
    mode="transcribe"
)
print(response.transcript)

快速开始（JavaScript/TypeScript）

import { SarvamAIClient } from "sarvamai";
import * as fs from "fs";

const client = new SarvamAIClient({ apiSubscriptionKey: "YOUR_SARVAM_API_KEY" });

const response = await client.speechToText.transcribe({
    file: fs.createReadStream("audio.wav"),
    model: "saaras:v3",
    mode: "transcribe"
});
console.log(response.transcript);

Batch API（长音频 + 说话人分离）

job = client.speech_to_text_job.create_job(
    model="saaras:v3",
    mode="transcribe",
    language_code="hi-IN",
    with_diarization=True,
    num_speakers=2
)
job.upload_files(file_paths=["meeting.mp3"])
job.start()
job.wait_until_complete()
job.download_outputs(output_dir="./output")

每个文件最长支持 2 小时，每个任务最多支持 20 个文件，最多支持 20 位说话人（num_speakers），以及全部 5 种输出模式。

WebSocket 流式传输

import asyncio, base64
from sarvamai import AsyncSarvamAI

async def stream_audio():
    client = AsyncSarvamAI()
    async with client.speech_to_text_streaming.connect(
        model="saaras:v3",
        language_code="hi-IN",   # required — connect() now rejects a missing language_code
        high_vad_sensitivity=True,
        flush_signal=True
    ) as ws:
        with open("audio.wav", "rb") as f:
            audio_base64 = base64.b64encode(f.read()).decode("utf-8")
        await ws.transcribe(audio=audio_base64, encoding="audio/wav", sample_rate=16000)
        await ws.flush()
        response = await ws.recv()
        print(response)

asyncio.run(stream_audio())

会话时长没有固定限制，但连接会在60 秒无活动后关闭。电话音频请使用 sample_rate=8000。

已通过实时测试：如果省略 language_code，connect() 当前会抛出 TypeError: ... missing 1 required keyword-only argument: 'language_code'——尽管某些文档示例没有将其标为必填项，但在已安装的 SDK 中它并非可选。

实时流式传输（新增——saaras:v3-realtime / saaras:v4）

这是一个较新且独立的 WebSocket API，并非对上述“WebSocket 流式传输”的替代；后者仍可正常使用。需要真正的中间结果和更精细的轮次控制时，请使用此 API。

import asyncio, base64
from sarvamai import AsyncSarvamAI, RealtimeAudioInput, RealtimeEnd

async def transcribe(audio_chunks):
    client = AsyncSarvamAI()
    async with client.speech_to_text_realtime_streaming.connect(
        language_code="hi-IN",
        stream_type="fast",   # "fast" | "balanced" (default) | "simulated"
    ) as ws:
        async def send_audio():
            async for chunk in audio_chunks:
                await ws.send_realtime_audio_input(
                    RealtimeAudioInput(audio=base64.b64encode(chunk).decode("utf-8"))
                )
            await ws.send_realtime_end(RealtimeEnd())

        async def receive_events():
            async for message in ws:
                if message.event == "transcript.partial":
                    print(f"partial: {message.text}")
                elif message.event == "transcript.final":
                    print(f"final: {message.text}")
                elif message.event == "error":
                    print(f"error ({message.code}): {message.message}")

        await asyncio.gather(send_audio(), receive_events())

JS：调用 client.speechToTextRealtimeStreaming.connect({ language_code, stream_type })，然后调用 socket.sendRealtimeAudioInput({...}) / socket.sendRealtimeEnd({...})，并通过 socket.on("message", ...) 监听事件。

注意事项

注意事项	详情
REST：30s 限制	音频超过 30s 会失败。较长的文件请使用 Batch API 或 WebSocket。
JS 方法名称	client.speechToText.transcribe({...}) — 使用驼峰命名法，而不是 speech_to_text。文件通过 fs.createReadStream() 传入。
WebSocket 编解码器	仅支持 wav、pcm_s16le、pcm_l16、pcm_raw。流式传输不支持 MP3/AAC/OGG。PCM 输入仅支持 16kHz。
WebSocket 音频	必须经过 base64 编码。电话音频请使用 sample_rate=8000。
WebSocket 空闲超时	连接会在 60s 不活动后关闭。对于长时间运行的会话，请定期发送静音（振幅接近零）音频块作为保活信号。
刷新信号	flush_signal=True + await ws.flush() 会强制立即生成转录边界。
VAD 事件	vad_signals=True 会在转录内容旁发出 START_SPEECH/END_SPEECH 事件。设置 high_vad_sensitivity=True 可自动检测语音结束。
短音频检测	对于少于 3 秒的音频，请明确设置 language_code — 自动检测需要更多信号。
keyterms 仅适用于 v4	REST、Batch 和两个 WebSocket 流式端点（旧版 /speech-to-text/ws 和实时端点）均支持通过 model="saaras:v4" 使用此参数。已在线验证：saaras:v3 + keyterms 会返回 400 — "'keyterms' is only supported by model 'saaras:v4', got 'saaras:v3'." — 这是硬错误，不会被静默忽略。格式：字符串的 JSON 列表，最多 50 个词条，每个词条最多 64 个字符 — 不要使用旧版 keyterm/hotwords 字段。
JS 对 keyterms 的支持	截至本文撰写时，文档称 JS speechToText.transcribe({..., keyterms}) 尚未发布到 npm，只有 speechToTextJob.createJob({..., keyterms})（Batch）可用。已针对 [email protected] 在线验证：REST transcribe({..., keyterms}) 可正常运行 — 文档中的说明可能已经过时。不要盲目相信任一来源；等你阅读本文时，这个差距可能已经消除 — 请实际调用一次进行测试。无论如何，Python 需要 sarvamai>=0.1.33a1（REST）/ >=0.1.33a3（Batch）。
Realtime 和旧版流式传输是不同的端点	旧版 WebSocket（/speech-to-text/ws、speech_to_text_streaming）没有中间结果，且需要重新连接才能更改参数。Realtime（/speech-to-text-realtime/ws、speech_to_text_realtime_streaming）增加了 transcript.partial 事件、毫秒级 VAD 参数（threshold、silence_duration_ms、min_speech_duration_ms）以及实时 config.update — 不要混用这两个 API 的参数名称。
Realtime 采样率	仅支持 8000 或 16000 Hz — 其他值会导致连接以代码 4000 关闭。

完整文档

可从以下链接获取流式协议、Batch API SDK 示例和编解码器详情：

• https://docs.sarvam.ai/llms.txt — 完整文档索引
• STT 概览
• 流式 API（旧版）
• Realtime 流式 API
• Keyterm 提示
• Batch API + 说话人分离
• 速率限制