text-to-speech

文本转语音 — Bulbul

在聊天中实时进行 TTS → sarvam-mcp（sarvam_tools_tts_*）。此技能 = SDK 代码。

重要

身份验证：使用 api-subscription-key 标头，而非 Authorization: Bearer。基础 URL：https://api.sarvam.ai（不是 /v1——该前缀仅用于兼容 OpenAI 的聊天端点） 以下代码所需的最低 SDK 版本：Python sarvamai>=0.1.29、JS sarvamai@>=1.1.8。较旧版本的 TTS 参数为 target_language_code——参见注意事项。

模型

bulbul:v4-flash——最新版本，新集成请使用此版本。与 v3 使用相同的 REST、HTTP 流式传输和 WebSocket 契约。200 多种角色语音（222 个 ID）。

bulbul:v3——省略 model 时 API 使用的模型。使用短名称（shubh、priya）。目前 Malayalam 和 Odia 仍应使用此模型，因为 v4 尚无这两种语言的角色语音。

说话人（v4 Flash）

ID 格式为小写的 voice_language_style：aparna_hi_customer、simran_en_customer、shubh_enhi_ads。省略 speaker 时，默认值为 shubh_enhi_ads。v2/v3 的短名称（shubh、priya、ishita、anushka）会返回 400 错误。

中间部分是语言标签（hi、en、bn、gu、kn、mr、pa、ta、te），或表示英语与印地语混合的 enhi。单次话语确实混合使用两种语言时，请使用 _enhi_ 角色语音；印地语文字中夹杂少量英语借词则无需使用。

language_code 仍接受常用的 BCP-47 值（hi-IN、en-IN 等，包括 ml-IN 和 od-IN）。没有 ml 或 od 角色语音 ID——对于这两种语言，请设置 model="bulbul:v3" 并使用 v3 短名称。

使用场景	印地语	英语
客户服务	aparna_hi_customer	aparna_en_companion
销售	aparna_hi_customer、shubh_hi_customer	simran_en_sales
催收	simran_hi_recovery	shubh_en_recovery
印地语与英语混用（单次话语）	simran_enhi_customer	—

请勿照抄 Voices 中“generate your own sample”代码片段里的 speaker="ishita"——这是 v3 短名称，在 v4-flash 中会失败。

各语言的覆盖情况（已于 2026-10-06 在线验证；每种语言列出一个可用角色语音，可从实时列表中选择其他语音）：

语言	示例角色语音	语言	示例角色语音
en-IN	simran_en_customer、sunny_en_social	mr-IN	ishita_mr_conversational
hi-IN	aparna_hi_customer、shubh_hi_customer	gu-IN	bhavik_gu_conversation
hi-IN（印地语与英语混用）	shubh_enhi_ads（默认值）	kn-IN	chaitra_kn_conversation
bn-IN	roopa_bn_conversational、arnab_bn_conversation	pa-IN	anand_pa_conversation
ta-IN	gokul_ta_narration、aravind_ta_ads	te-IN	kavitha_te_conversation

角色语音列表会变动。 Sarvam 于 2026-10-06 重命名了语音（bappa_bn_conversation → arnab_bn_conversation、vetri_ta_ads/vetri_ta_suspense → aravind_ta_*），旧 ID 现在会返回 400 错误。不要凭记忆或旧博客文章硬编码 ID。未知说话人会返回 400 错误，并附带完整的实时列表，因此只需一次错误请求即可获取该列表。API 还列出了 2 个文档目录中没有的 Assamese（_as_）角色语音。

快速入门（Python）

from sarvamai import SarvamAI
from sarvamai.play import save

client = SarvamAI()

response = client.text_to_speech.convert(
    text="नमस्ते, आप कैसे हैं?",
    language_code="hi-IN",
    model="bulbul:v4-flash",
    speaker="aparna_hi_customer",
    enable_preprocessing=True,
)
save(response, "output.wav")

# HTTP Stream (lower latency, binary audio)
chunks = []
for chunk in client.text_to_speech.convert_stream(
    text="Hello from Sarvam AI",
    language_code="en-IN",
    model="bulbul:v4-flash",
    speaker="simran_en_customer",
    output_audio_codec="wav",
):
    chunks.append(chunk)
audio = b"".join(chunks)

快速入门（JavaScript/TypeScript）

import { SarvamAIClient } from "sarvamai";
import { writeFile } from "fs/promises";

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

// REST
const response = await client.textToSpeech.convert({
    text: "नमस्ते, आप कैसे हैं?",
    language_code: "hi-IN",
    model: "bulbul:v4-flash",
    speaker: "aparna_hi_customer",
    enable_preprocessing: true,
});

// HTTP Stream (lower latency, returns BinaryResponse)
const streamResponse = await client.textToSpeech.convertStream({
    text: "Hello from Sarvam AI",
    language_code: "en-IN",
    model: "bulbul:v4-flash",
    speaker: "simran_en_customer",
    output_audio_codec: "wav",
});
const bytes = await streamResponse.bytes();
await writeFile("output.wav", bytes);

WebSocket 流式传输

import asyncio
from sarvamai import AsyncSarvamAI

async def tts_stream():
    client = AsyncSarvamAI()
    async with client.text_to_speech_streaming.connect(model="bulbul:v4-flash") as ws:
        await ws.configure(
            target_language_code="hi-IN",
            speaker="aparna_hi_customer",
            output_audio_codec="wav",
        )
        await ws.convert("Your text here")
        await ws.flush()
        async for message in ws:
            pass  # base64 audio chunks

asyncio.run(tts_stream())

字符数限制

方法	文本上限
REST（convert）	2,500 个字符
HTTP 流式传输（convert_stream）	3,500 个字符
旧版 inputs 数组（原始 REST）	每项 500 个字符——改用 text 可将上限提高到 2,500 个字符
WebSocket	每条消息 2,500 个字符（为获得最低延迟，请保持在 500 个字符以内；可通过同一连接发送多条消息）

注意事项

注意事项	详情
设置 model，否则会使用 v3	省略 model 时会选择 bulbul:v3。此时 v3 短名称可用，v4 persona ID 则不可用。新代码应设置 model="bulbul:v4-flash"。
v4 不支持 v3/v2 短名称	shubh、priya、ishita、anushka 等名称会被拒绝。请使用 voice_language_style。未知 ID 会返回 400，并附带实时说话人列表。
language_code 受版本限制	Python >=0.1.29 和 JS >=1.1.8（两者均于 2026-08-03 发布）使用 language_code；较早版本使用 target_language_code。这是硬性重命名——没有别名或弃用兼容层，JSON 请求体中的键也已更改，因此使用错误名称会在发送请求前引发 TypeError。如果遇到此问题，请运行 pip show sarvamai / npm ls sarvamai 检查版本。
WebSocket 的参数名称未更改	Python ws.configure() 仍使用 target_language_code（在线路上传递时映射为 language_code）。如果文档示例将 language_code= 传给 ws.configure()，会引发 TypeError。JS configureConnection() 使用 language_code。
JS 方法名称	client.textToSpeech.convert({...}) 和 .convertStream({...})——采用驼峰命名法。流式响应会返回 BinaryResponse，支持 .stream()、.bytes() 和 .blob()。
pitch / loudness 的取值范围	pitch 为 −0.5–0.5（默认值为 0），loudness 为 0.1–2.5（默认值为 1），pace 为 0.5–2.0。超出范围的值会返回 400。Bulbul v3 过去不接受 pitch / loudness；截至 2026-10-06，这些参数也已可用（经实时验证）。模型页面限制表中仅适用于 v2 的取值范围不适用。
流式传输的默认编解码器	HTTP 流和 WebSocket 默认不使用 WAV。请设置 output_audio_codec（wav 或 mp3；HTTP 流还支持 flac / aac）。架构中可能会出现 opus，但目前它会在 /text-to-speech 上报错。
采样率	已在 v4-flash REST 上验证 speech_sample_rate 的 8000、16000、24000 和 48000 取值（返回的 WAV 与请求的采样率一致）。
采样率高于 24kHz	32kHz、44.1kHz、48kHz 仅支持 REST，不支持流式传输。省略时默认值为 22050 Hz。
REST 响应	音频以 Base64 编码，位于 response.audios[0]。请使用 sarvamai.play.save() 或 base64.b64decode()。将原始 Base64 字符串写入磁盘不会得到可播放的音频。
说话人必须与模型匹配	两种不匹配情况都会失败：在 bulbul:v4-flash 上使用 v3 短名称，或在 bulbul:v3 上使用 v4 persona，都会返回 400。请明确配对 model 和 speaker。
不支持 SSML	不支持 SSML 标记。请使用 pace（以及 v4 上的 pitch / loudness），并按句子边界分块。
使用原生文字书写	使用罗马字母转写的印度语输入（“Aapka order confirm ho gaya hai”）会降低质量。请用原生文字书写印度语词汇；英文外来词保留拉丁字母（“आपका order confirm हो गया है”）。启用 enable_preprocessing=true 时，请勿手动展开数字、日期或货币。
ml-IN / od-IN 没有 v4 persona	这些代码可接受，但目录中没有马拉雅拉姆语或奥里亚语 ID。这些语言请使用 bulbul:v3。
发音词典	在 v4-flash 上传入 dict_id 的方式与 v3 相同（每位用户 10 个词典，每个词典 100 个词）。使用 Python client.pronunciation_dictionary.create(file=f) 创建。JS SDK 上传功能存在问题（缺少 multipart Content-Type）——请改用原始 fetch 和 FormData，并明确指定 Blob 类型。发音页面限制表中标注“仅限 v3”的行已过时；该页面的示例会将 dict_id 与 bulbul:v4-flash 一起发送。

完整文档

从以下链接获取语音目录、精选推荐、流式传输协议和编解码器选项：

• https://docs.sarvam.ai/llms.txt — 完整的文档索引
• Bulbul 模型
• 语音（v4 目录 + v3 预览）
• Bulbul v4 Flash 最佳实践
• TTS 概览
• HTTP 流式传输
• 发音词典
• 速率限制