mcpField
T
text-to-speech

text-to-speech

github.com/deepgram创意与媒体2644 次安装4 天前更新
代码仓库

关于 text-to-speech

此技能为开发者提供 Deepgram 文本转语音集成指引，涵盖 Aura 和 Flux TTS 端点、语音选择、流式与批量请求及其控制选项。

主要功能

  1. 01选择 Aura 或 Flux TTS 端点
  2. 02通过 WebSocket 流式生成语音
  3. 03通过批量请求生成音频
  4. 04选择语音及语言变体
  5. 05设置语速、发音和停顿控制

适用场景

  1. 01构建支持打断处理的流式语音 Agent
  2. 02生成语音文件或 IVR 提示
  3. 03配置多语言语音输出

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/deepgram/skills --skill text-to-speech

安装后在 Claude Code 中输入/text-to-speech确认已加载。

详细介绍

Deepgram 文本转语音

Deepgram 在不同的端点上提供两个文本转语音系列，两者的语音不重叠。 Aura 语音只能用于 /v1/speak。Flux TTS 语音只能用于 /v2/speak。/v2/speak 是一个新增端点。/v1/speak 未作更改，仍受支持。

先选择系列

需求系列端点
流式传输 LLM 输出且必须能应对插话的语音 AgentFlux TTSwss://api.deepgram.com/v2/speak
单次生成音频：文件、IVR 提示词、通知Flux TTS 批量模式POST https://api.deepgram.com/v2/speak
在同一条响应中切换英语和西班牙语Aura-2 代码切换语音/v1/speak
Voice Agent 中的非英语语音Aura-2agent.speak.provider.version: "v1"
必须保留的现有 aura-2-* 或 aura-{voice}-en 语音Aura-2 或 Aura-1/v1/speak

经验法则：对于任何新的构建，推荐使用 Flux TTS 系列，可支持其 42 种语言中的任意一种。 Flux TTS 语音支持英语（美国、英国、爱尔兰、澳大利亚、印度、新加坡和菲律宾口音）及其他 41 种语言；语言名称是模型字符串的后缀（flux-anouk-nl 是荷兰语）。文本规范化（数字、日期、缩写）支持英语、德语、荷兰语、法语、印地语、意大利语、日语、葡萄牙语、俄语和西班牙语；其他 32 种语言为 Early Access，不支持文本规范化，因此请将数字和日期写成文字。非英语语音可通过 api.deepgram.com、api.eu.deepgram.com 和 api.in.deepgram.com 提供，目前尚未通过 api.au.deepgram.com 提供。Aura-2 是上一代产品（支持英语、西班牙语、德语、法语、荷兰语、意大利语和日语），Aura-1 是第一代产品，仅支持英语。在 Voice Agent 中，非英语语音以及压缩或封装格式的输出需要使用 Aura（v1）语音（参见错误 7）。

首个请求：通过 REST 使用 Aura

curl --request POST \
  --url "https://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&container=wav" \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text": "Hello, how can I help you today?"}' \
  --output hello.wav \
  --fail-with-body --silent || echo "Request failed"

预期行为：

  • 2xx 响应正文是二进制音频。错误响应为 JSON。解析前请检查 HTTP 状态。
  • 选项放在查询字符串中。JSON 正文仅包含 text。
  • 如果未指定 encoding，REST 将返回 mp3。对于 WAV，请发送 encoding=linear16&container=wav。其他 REST 编码包括：opus、flac、aac、mulaw、alaw，并可搭配 container、bit_rate、sample_rate。
  • 如果省略 model，/v1/speak 将使用 aura-asteria-en，这是一种 Aura-1 语音。请务必设置 model。
  • Aura-2 的 speed 接受 0.7 到 1.5，且仅适用于英语和西班牙语语音。西班牙语语音请使用 0.9 到 1.5；低于 0.9 的值可能会导致语流不连贯。
  • Aura-2 发音控制已在 /v1/speak 正式发布，英语和西班牙语语音均可使用，与 Flux TTS 使用相同的转义语法 \{"word":"...","pronounce":"<IPA>"\}，输入上限为 2000 个字符。Aura-2 不支持停顿控制。

通过 WebSocket 使用 Aura

使用相同的 Authorization: Token 标头连接到 wss://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&sample_rate=24000。 发送 JSON 文本帧：{"type":"Speak","text":"..."} 用于排入文本，{"type":"Flush"} 用于强制输出音频，{"type":"Clear"} 用于清空缓冲区，{"type":"Close"} 用于结束。音频以二进制帧形式传入；Metadata、Flushed、Cleared 和 Warning 以 JSON 形式传入。LLM 完成响应后发送 Flush。每 60 秒最多发送 20 次 Flush。流式输出仅支持原始 linear16（默认）、mulaw 或 alaw。

Aura 套接字的限制：每个请求最多 2000 个文本字符（关闭代码 1009，负载 BIG-0001），每分钟发送到套接字的文本总计最多 2400 个字符（统计所有 Speak 消息；关闭代码 1008，DATA-0001），每个连接从初始连接开始最多持续 60 分钟（关闭代码 1011，NET-0003）；如需进行更长时间的对话，请打开新套接字。关闭帧代码以及升级失败时的 dg-error 标头列于 https://developers.deepgram.com/docs/tts-troubleshooting-websocket-net-and-data-errors。区域主机 api.eu.deepgram.com、api.au.deepgram.com 和 api.in.deepgram.com 均提供 /v1/speak、REST 和 WebSocket 服务，并使用相同的密钥。

面向语音 Agent 的 Flux TTS

连接到 wss://api.deepgram.com/v2/speak?model=flux-haley-en。必须指定 model，且必须是 flux-* 语音。没有默认值，并且会拒绝 Aura 字符串。要在区域内处理，请使用 wss://api.eu.deepgram.com/v2/speak、wss://api.au.deepgram.com/v2/speak 或 wss://api.in.deepgram.com/v2/speak；如果某个区域不可用，请求会失败，而不会路由到其他区域。

一个会话由一系列轮次组成。流式传入 token，然后结束该轮次：

{"type": "Speak", "text": "Sure, I can "}
{"type": "Speak", "text": "help you cancel your subscription."}
{"type": "Flush"}
  • 音频会在你调用 Flush 之前开始流式传输。Flush 会结束当前轮次；随后服务端会发送 Flushed 和 SpeechMetadata，其中包含计费和时间信息。将 SpeechMetadata 视为轮次结束标志；Flushed 会更早到达。
  • 服务端会在每轮的 SpeechStarted 和 SpeechMetadata 中分配 speech_id。切勿自行发送。
  • 第一条消息是 Connected，包含 request_id、model_name、model_version 和 model_uuids。 正常关闭时的最后一条消息是 SessionMetadata，其中包含会话累计总量；Interrupt 会根据客户端实际播放的音频， 重新计算 total_audio_duration_ms。
  • 服务端的 JSON 消息包括 Connected、SpeechStarted、Flushed、SpeechMetadata、 SpeechInterrupted、ConfigureSuccess、ConfigureFailure、Warning、Error 和 SessionMetadata。 Warning 包含 code 和 description，但不会关闭会话。Error 是致命错误：每个 DOMAIN-NNNN 代码（MESSAGE-0000、DATA-0000、DATA-0002、BIG-0000、NET-0000 到 NET-0004）之后都会关闭 WebSocket。
  • 用户打断时，先停止本地播放，然后发送 {"type":"Interrupt","playback_offset":{"type":"time_ms","value":2340}}。
    • SpeechInterrupted 会返回 text_spoken 和 text_remaining；将 text_spoken 反馈到 LLM 上下文中。不提供 playback_offset 时，不会返回文本拆分结果。
    • value 表示自会话开始以来已播放的毫秒数，而非自本轮开始以来的毫秒数。每次 Interrupt 的偏移量都必须大于上一次，否则会因 INVALID_INTERRUPT_OFFSET 被忽略。读取 SpeechInterrupted 中的 audio_played_ms，作为下一个偏移量的基准。
  • {"type":"Configure","speed":1.15} 可在会话中途更改语速；更改会在下一个片段边界生效。 speed 的范围为 0.5 到 1.5，步进为 0.05，默认值为 1.0。
    • 服务端会通过 ConfigureSuccess 返回已应用的配置 applied；或者通过 ConfigureFailure 返回 code 和 description（如果失败与某个字段有关，还会返回 field 和 value），并保留之前的配置。
    • 0.45 和 1.55 会返回 'speed' must be between 0.5 and 1.5，而 1.07 会返回 'speed' must be provided in increments of 0.05。
    • ConfigureFailure 代码包括：SPEED_OUT_OF_RANGE、SPEED_INCREMENT_INVALID、SPEED_NOT_SUPPORTED、 CONTROL_COMBINATION_INVALID（排队的轮次仍携带发音控制；请先对该轮次执行 Flush）以及 INTERNAL_ERROR（配置有效，但服务端无法应用）。
  • expressivity 的范围为 -2（平静）到 2（生动），默认值为 0。必须为整数。无效值会在 WebSocket 升级完成前被拒绝，并返回 HTTP 400，因此不会收到 Connected 消息：小数值（如 1.5）会返回 EXPRESSIVITY_INCREMENT_INVALID，超出 -2 到 2 范围的值会返回 EXPRESSIVITY_OUT_OF_RANGE。该参数处于 Beta 阶段，每个连接建立后固定不变（Configure 无法更改），且目前仅对 0 的生产环境使用情形进行了验证。
  • Flux TTS /v2/speak 的发音控制处于 Early Access 阶段（Aura-2 /v1/speak 已正式发布，参见 Aura REST 部分）。它是在文本中使用转义 JSON 对象，适用于 WebSocket 和批量请求： \{"word":"dupilumab","pronounce":"duːˈpɪljuːmæb"\}。
    • 限制：每个请求最多 500 条；IPA 最多 128 个字符，且不得超过源词长度的 10 倍，最小上限为 15。
    • 仅在 speed 为 1.0 时有效：在 WebSocket 中，如果会话以其他语速开启时发送发音控制，或发送已由 Configure 设置的语速值，会导致连接因 DATA-0002 失败；在批量请求中，请求会返回 400 CONTROL_COMBINATION_INVALID。
    • 无效的 IPA 仍会尽力应用，并通过 WebSocket 上的 PRONUNCIATION_WARNINGS 警告以及批量请求中的 dg-warnings 响应头报告。
    • 语法和 IPA 指南：https://developers.deepgram.com/docs/tts-voice-controls
  • 暂停控制 \{pause:500ms\} 仅适用于批量请求。
    • 限制：500 到 3000 ms，步进为 100 ms；每个请求最多 8 个；相邻暂停之间必须有文本；存在暂停时， speed 上限为 1.15（PAUSE_SPEED_CAP_EXCEEDED）。暂停时长与请求时长的偏差约在 100 ms 以内。
    • 在 WebSocket 上使用暂停标记会导致连接因 DATA-0002 失败；暂停与发音控制组合使用会被 CONTROL_COMBINATION_INVALID 拒绝。
    • 其他批量请求的 400 错误代码包括：BREAK_OUT_OF_RANGE、BREAK_INCREMENT_INVALID、BREAKS_LIMIT_EXCEEDED 和 BREAK_SYNTAX_INVALID。触发该错误的情况有两种：使用不带反斜杠的简单标记，或使用带反斜杠的结构化标记。
    • 可接受的形式包括 \{pause:500\}（纯数字表示毫秒）、\{pause:500ms\}、 \{pause:1.5s\}，以及未转义的结构化形式 {pause:{duration_ms:500}}。
  • 每轮的 SpeechMetadata.controls_applied 会统计 pronunciations_applied、breaks_applied 和 pronunciation_warnings；批量请求会通过 dg-pronunciations-applied 和 dg-breaks-applied 响应头返回统计结果。
  • WebSocket 仅流式传输原始音频，默认格式为 linear16（参见错误 5）。仅适用于批量请求的参数 （container、bit_rate、callback、callback_method、priority）以及任何未知参数都会导致连接失败。
  • 空闲会话会在 60 秒后关闭（NET-0004）；两轮之间无活动时，请发送 WebSocket Ping。每个会话都会在 1 小时后关闭 （NET-0003）。
  • 批量请求：POST https://api.deepgram.com/v2/speak?model=flux-haley-en，正文为 {"text": "..."}，会返回一条 音频响应；默认格式为 mp3，支持 opus、flac、aac、container、bit_rate，且只有这种传输方式支持内联暂停。
  • SDK：每个 Deepgram SDK 都包含 Flux TTS 客户端。Python、JavaScript 和 Java 将其命名为 speak.v2； .NET 提供 FluxSpeakRESTClient 和 FluxSpeakWebSocketClient；Rust 提供 speak::flux；Go 从 v3.8.0 起提供 pkg/client/speak/v2。只有 Rust SDK 技能文档完整介绍了 Flux TTS；Python 技能包含一个 Flux 批量请求部分 （使用其 TextBuilder 辅助工具），而 JS、Java、Go 和 .NET 的 text-to-speech SDK 技能仅介绍 /v1/speak， 因此请从本技能文档中获取 /v2/speak 的消息格式。

语音

  • Aura：英语、西班牙语、德语、法语、荷兰语、意大利语和日语使用 aura-2-{voice}-{lang}，此外还有 12 种 Aura-1 英语语音，名称为 aura-{voice}-en。其中 5 种西班牙语语音可在一次请求中切换使用英语和西班牙语：aura-2-aquila-es、aura-2-carina-es、aura-2-diana-es、aura-2-javier-es 和 aura-2-selena-es。语音目录：https://developers.deepgram.com/docs/tts-models
  • Flux TTS：使用带有双字母语言后缀的 flux-{voice}-{language}，支持英语和另外 41 种语言。不同地区的变体共用相同后缀：巴西葡萄牙语和欧洲葡萄牙语都使用 -pt，佛兰芒语使用 -nl，瑞士德语使用 -de，普通话、台湾普通话和粤语都使用 -zh，因此请从目录中按名称选择语音。推荐的英语语音包括 flux-haley-en、flux-alexis-en 和 flux-kit-en。语音目录：https://developers.deepgram.com/docs/flux-tts/voices

定价

Flux TTS、Aura-2 和 Aura-1 的文本转语音费用均按输入文本的每 1,000 个字符计费。费率因模型和套餐而异，且会随时间变化。请在 https://deepgram.com/pricing 查看费率；不要凭记忆引用价格。

常见错误

  1. 认证方案错误。API 密钥应放在 Authorization: Token <key> 中。Bearer 仅用于 POST https://api.deepgram.com/v1/auth/grant 返回的短时 JWT。使用 Bearer 发送密钥会返回 401。

  2. 误读模型错误。不存在的模型名称（包括拼写错误）会返回 400： {"err_code":"Bad Request","err_msg":"Bad Request: No such model/language/tier combination found."}。 模型存在，但你的项目无权使用时，会返回 403： {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."}。遇到 400 时，请对照上方目录检查名称；只有遇到 403 时才申请访问权限。

    GET https://api.deepgram.com/v1/models 返回的是公开目录，而不是你的密钥可使用的模型。其 tts 列表中只有 Aura 语音，没有任何 flux-* 条目，因此请在 https://developers.deepgram.com/docs/flux-tts/voices 查看 Flux TTS 语音名称。

  3. 将音频解析为 JSON。这两个端点的成功响应体都是字节。请先根据状态码分支处理。

  4. 混淆两类语音。在 /v2/speak 上使用 Aura 语音，或在 /v1/speak 上使用 Flux TTS 语音，都会失败；/v2/speak 也会拒绝缺少 model 的请求。

  5. 向 WebSocket 请求 mp3。这两个端点的流式响应都是原始音频。需要压缩输出时，请使用 REST。

  6. 以为 Flux TTS 会整理文本。Speak 文本会原样拼接，因此 "Hello world." 后接 "How are you?" 会变成 "Hello world.How are you?"。拼接回复、工具结果和另一条回复时，请插入空格。

    请发送纯文本。系统不会解析 SSML；Flux TTS 仅支持其自身的转义控制标记，其中发音标记适用于两种传输方式，暂停标记仅适用于批处理。检测到的 SSML、ElevenLabs 和 Cartesia 标签会被剥除，每个 Speak 会产生一条 INPUT_MARKUP_STRIPPED 警告；检测器未识别的标记（Markdown、HTML、自定义 XML）会原样转发，并可能被读出。参见 https://developers.deepgram.com/docs/flux-tts/client-messages。

  7. 将 Voice Agent 指向 api.deepgram.com。Voice Agent API 位于 wss://agent.deepgram.com，并根据 agent.speak.provider.version 选择 TTS 类型：Flux TTS 使用 v2，Aura 使用 v1。省略 agent.speak 时，默认使用 Flux TTS 和 flux-kit-en。

    • Agent 仅接受英文 Flux TTS 语音；目前其他 41 种语言仅支持 /v2/speak，因此非英文 Agent 语音应使用 Aura-2（v1）语音或第三方提供商。
    • Agent 中的语速和 expressivity 应设置在 agent.speak.provider 中；参见 https://developers.deepgram.com/docs/voice-agent-tts-controls。
    • 行内暂停标记不会被读出，也不会返回错误，因此包含此标记的文本会变成静音；请通过标点和数字分组来控制节奏。
    • 在 audio.output 中指定压缩编码（mp3、opus、flac、aac）或 wav 等容器会返回 INVALID_SETTINGS；因此，对于这些格式，请配置 Aura（v1）语音，包括省略 agent.speak 的情况。

  8. 在不支持语音控制的语言中使用这些控制。Flux TTS 的 speed、暂停和发音功能仅适用于英文语音；Aura-2 的语速和发音功能仅支持英语和西班牙语。对于其他语音，请改用标点来控制语速。

以下情况请使用其他技能

  • 需要查看所有参数、枚举或消息架构：使用 api 技能，文件为 references/speak.md。
  • 需要查看无法确定名称的文档页面：使用 docs 技能。
  • 想要可运行的应用：使用 starters 技能。功能包括 text-to-speech（Aura REST）、 live-text-to-speech（Aura WebSocket）和 flux-tts（仅限 node、flask、fastapi、django、java）。
  • 想要一段少于 50 行的代码片段：使用 recipes 技能。Recipes 仅涵盖 /v1/speak 上的 Aura；目前 还没有 Flux TTS recipes。
  • 想要接入第三方平台：使用 examples 技能（目前支持 Aura）。如需通过 Twilio 使用 Flux TTS， 请参考 https://developers.deepgram.com/docs/twilio-and-deepgram-tts，该功能需要 deepgram-sdk 7.6.0 或更高版本。
  • 想在编码工具中查看文档：使用 setup-mcp 技能。
  • 想要某种语言的惯用代码：使用 SDK 仓库中的 deepgram-{js,python,java,go,rust,dotnet}-text-to-speech 技能（例如 npx skills add deepgram/deepgram-python-sdk）。只有 Rust SDK 技能完整记录了 Flux TTS； 请参阅 Flux TTS 部分中的 SDK 列表。
  • 想让 Deepgram 通过一个连接运行语音转文本、大模型和 TTS：使用 voice-agent 技能和 deepgram-{lang}-voice-agent。
  • 要进行转录而非语音合成：使用 speech-to-text 技能。请注意，“Flux”既指 /v2/listen 上的 语音转文本产品，也指 /v2/speak 上的这款文本转语音产品。

资料来源

每个页面均提供 Markdown 版本（在任意 URL 后添加 .md）；索引位于 https://developers.deepgram.com/llms.txt。

评论

支持 Markdown