deepgram-js-text-to-speech

使用 Deepgram 文本转语音（JavaScript / TypeScript SDK）

通过一次性 REST 生成，或经由 /v1/speak 进行低延迟流式合成，将文本转换为音频。

何时使用此产品

• REST（client.speak.v1.audio.generate） — 将完整文本渲染为音频响应。适用于可下载文件、预生成提示词和批量合成。
• WebSocket（client.speak.v1.createConnection() / connect()） — 流式输入文本并接收音频输出，延迟更低。适用于 LLM 仍在生成令牌的场景。

以下情况请使用其他技能：

• 需要 Agent 同时聆听、思考并处理打断 → deepgram-js-voice-agent

身份验证

require("dotenv").config();

const { DeepgramClient } = require("@deepgram/sdk");

const deepgramClient = new DeepgramClient({
  apiKey: process.env.DEEPGRAM_API_KEY,
});

仓库中的示例使用 require("../dist/cjs/index.js")，但应用代码通常应从 @deepgram/sdk 导入。

快速入门 — REST（一次性）

摘自 examples/10-text-to-speech-single.ts：

const data = await deepgramClient.speak.v1.audio.generate({
  text: "Hello, this is a test of Deepgram's text-to-speech API.",
  model: "aura-2-thalia-en",
  encoding: "linear16",
  container: "wav",
});

console.log("Audio generated successfully", data);

generate(...) 返回的是 BinaryResponse，而不是 JSON。有关 .stream()、.arrayBuffer()、.blob() 和 .bytes() 的处理方式，请参阅 examples/25-binary-response.ts。

快速入门 — WebSocket（流式）

摘自 examples/11-text-to-speech-streaming.ts：

const deepgramConnection = await deepgramClient.speak.v1.createConnection({
  model: "aura-2-thalia-en",
  encoding: "linear16",
});

deepgramConnection.on("message", (data) => {
  if (typeof data === "string" || data instanceof ArrayBuffer || data instanceof Blob) {
    console.log("Audio received");
  } else if (data.type === "Flushed") {
    deepgramConnection.close();
  }
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

deepgramConnection.sendText({ type: "Speak", text: "Hello from streaming TTS." });
deepgramConnection.sendFlush({ type: "Flush" });

关键参数 / API 接口

• REST 和 WSS：model、encoding、sample_rate、container、bit_rate、callback、callback_method、tag、mip_opt_out。
• REST 响应接口（examples/25-binary-response.ts）：response.stream()、response.arrayBuffer()、response.blob()、response.bytes()、response.bodyUsed。
• WSS 客户端消息（src/api/resources/speak/resources/v1/client/Socket.ts）：sendText(...)、sendFlush(...)、sendClear(...)、sendClose(...)。
• WSS 服务端事件：二进制音频载荷，以及 Metadata、Flushed、Cleared、Warning。

限制

与 Python SDK 不同，此仓库不包含手写的 TextBuilder 辅助工具。如果要在调用 sendText(...) 前逐步缓冲令牌，请在应用层构建该辅助工具。

API 参考（分层）

1. 仓库内参考资料：reference.md → REST 的 Speak V1 Audio；WSS 行为见 src/CustomClient.ts 和 src/api/resources/speak/resources/v1/client/{Client,Socket}.ts。
2. 规范 OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. 规范 AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
4. Context7：库 ID /llmstxt/developers_deepgram_llms_txt
5. 产品文档：
   • https://developers.deepgram.com/reference/text-to-speech/speak-request
   • https://developers.deepgram.com/reference/text-to-speech/speak-streaming
   • https://developers.deepgram.com/docs/tts-models

注意事项

1. REST 返回二进制数据，而非 JSON。 应将结果视为流式 / 二进制响应体。
2. 使用自定义客户端包装器。 src/CustomClient.ts 会修补二进制 WebSocket 处理；生成的套接字对 JSON 的假设过于激进。
3. createConnection() 是惰性的。 注册处理程序后，调用 connect() 和 waitForOpen()。
4. 文本发送后调用 Flush。 如果不调用 sendFlush({ type: "Flush" })，末尾音频可能无法及时输出。
5. 流式文本采用结构化 JSON。 发送 { type: "Speak", text }，不要发送原始字符串。
6. 音频载荷形态因运行时而异。 同一个处理程序可能收到 string、ArrayBuffer 或 Blob。
7. 选择与接收端相匹配的编码 / 容器 / 采样率。 不匹配可能导致静电杂音、静音或文件无法播放。

此仓库中的示例文件

• examples/10-text-to-speech-single.ts
• examples/11-text-to-speech-streaming.ts
• examples/25-binary-response.ts

核心产品技能

要获取跨语言的 Deepgram 产品知识——整合后的 API 参考、文档查找工具、可直接运行的专项示例、第三方集成示例和 MCP 设置——请安装核心技能：

npx skills add deepgram/skills

此 SDK 提供符合语言习惯的代码技能；deepgram/skills 提供跨语言产品知识（参见 api、docs、recipes、examples、starters、setup-mcp）。