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（最新版） — 同じモードと言語に加え、Global English（インド英語だけではありません）と キータームプロンプトに対応しています。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 ストリーミング」の置き換えではなく、そちらも引き続き利用できます。真の中間結果と、より細かなターン制御が必要な場合はこちらを使用してください。

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：30 秒制限	30 秒を超える音声は失敗します。より長いファイルには 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 のアイドルタイムアウト	60 秒間操作がないと接続が閉じます。長時間実行するセッションでは、接続を維持するため、定期的に無音（振幅がほぼゼロ）の音声チャンクを送信してください。
フラッシュ信号	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 フィールドは使用しないでください。
keyterms の JS サポート	執筆時点のドキュメントによると、JS の speechToText.transcribe({..., keyterms}) は npm でまだリリースされておらず、動作するのは speechToTextJob.createJob({..., keyterms})（Batch）のみです。[email protected] に対して実機で検証したところ、REST の transcribe({..., keyterms}) はエラーなしで動作しました。ドキュメントの記載はすでに古くなっている可能性があります。どちらの情報源も鵜呑みにしないでください。この記事を読む頃には問題が解消されている可能性があるため、実際に呼び出して一度テストしてください。Python ではいずれの場合も、REST には sarvamai>=0.1.33a1、Batch には sarvamai>=0.1.33a3 が必要です。
リアルタイムとレガシーストリーミングは別のエンドポイントです	レガシー WebSocket（/speech-to-text/ws、speech_to_text_streaming）には中間結果がなく、パラメーターの変更には再接続が必要です。リアルタイム（/speech-to-text-realtime/ws、speech_to_text_realtime_streaming）では、transcript.partial イベント、ミリ秒単位の VAD パラメーター（threshold、silence_duration_ms、min_speech_duration_ms）、実行中の config.update が追加されています。2 つの API のパラメーター名を混同しないでください。
リアルタイムのサンプルレート	8000 または 16000 Hz のみです。それ以外の値を指定すると、コード 4000 で接続が閉じます。

詳細なドキュメント

ストリーミングプロトコル、Batch API の SDK サンプル、コーデックの詳細は、以下を参照してください。

• https://docs.sarvam.ai/llms.txt — 包括的なドキュメントの索引
• STT の概要
• ストリーミング API（レガシー）
• リアルタイムストリーミング API
• キータームのプロンプト指定
• Batch API と話者分離
• レート制限