mcpField
S
speech-to-text

speech-to-text

github.com/deepgram开发2763 次安装6 天前更新
代码仓库

关于 speech-to-text

这是一个 Deepgram Skill，指导开发者选择 Nova 或 Flux STT，并发起首次转录请求。内容侧重模型选择、端点和主要差异；详细参数参考另见 `api` Skill。

主要功能

  1. 01比较 Nova 与 Flux STT
  2. 02选择端点和模型
  3. 03开始预录音频转录
  4. 04通过 WebSocket 流式传音频
  5. 05配置轮次检测

适用场景

  1. 01转录录制音频
  2. 02生成字幕
  3. 03构建带轮次检测的语音界面
  4. 04选择 Deepgram 语音模型

安装

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

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

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

详细介绍

Deepgram 语音转文本

Deepgram 通过两个端点上的两类模型转录音频。请先选择模型系列；端点、参数和消息格式都取决于这一选择。本技能将帮助你完成第一个请求，并说明接下来要打开哪个技能。它不会重复完整的参数参考；相关内容请参阅 api 技能。

先选择模型系列

NovaFlux STT
模型名称nova-3（nova-3-general 的别名）、nova-3-medical、nova-3-pharmaflux-general-en（英语）、flux-general-multi（10 种语言）
端点/v1/listen，支持 REST 和 WebSocket/v2/listen，仅支持 WebSocket
输出转录文本流TurnInfo 事件，包含轮次状态和每轮的转录文本
轮次检测未内置；需使用 endpointing 和自定义逻辑内置：StartOfTurn、EagerEndOfTurn、TurnResumed、EndOfTurn
格式化和分析smart_format、diarize_model、summarize、sentiment、topics、intents、脱敏词级时间戳、numerals、redact（numbers 或 aggressive_numbers）、keyterm、profanity_filter、mip_opt_out、tag；不支持智能格式化和说话人分离
语言language=<code>；或使用 language=multi 进行语码转换，此时 language_hint 用于提供偏向模型名称决定语言；language_hint 用于为 flux-general-multi 提供偏向

选择规则：

  • 转录录制文件、生成字幕、需要说话人标签、需要摘要或情感分析，或者流式传输音频且由自己的代码判断短语何时结束时，选择 Nova。
  • 当有人与软件交谈，而软件必须知道对方何时停止说话时，选择 Flux STT：例如语音 Agent、电话助手、IVR、Agent 辅助。Flux 不支持预录制模式。
  • 如果你希望 Deepgram 同时运行大模型并朗读回复，请不要选择这两者。这是语音 Agent API，由单独的主机 agent.deepgram.com 提供服务。请打开 voice-agent 技能。

首次请求：对预录制文件使用 Nova

在 https://console.deepgram.com 创建密钥，并将其导出为 DEEPGRAM_API_KEY。密钥放在 Authorization 标头中，使用 Token 方案。始终传入 model；否则 API 会回退到 base。

curl -s -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://dpgr.am/spacewalk.wav"}'

转录文本位于 results.channels[0].alternatives[0].transcript。如需改为发送本地文件，请将 Content-Type 设为音频类型（例如 audio/wav），并使用 --data-binary @file.wav，不附带 JSON 请求体。

以下是你常用的 Nova 选项，都是 /v1/listen 的查询参数：

  • smart_format=true 会添加标点、分段和数字格式。它会启用 punctuate，因此不要同时设置这两项。
  • diarize_model=latest 会标注说话人。它取代了已弃用的 diarize=true；同时设置两者的请求会被拒绝。流式传输仅接受 latest 和 v1。
  • language=multi 可转录 55 种 Nova-3 多语言语种中的跨语种切换语音。也可以使用任何单一语言代码；默认值为 en。
  • language_hint=<code> 可按语言重复设置（language_hint=en&language_hint=es），使 language=multi 倾向于你预期的语言，但不会限制识别范围。与其他任何 language 值同时使用时会被忽略；使用不在 Nova-3 多语言列表中的代码会导致 400 错误（流式传输时会拒绝 WebSocket 握手）；提示在整个流期间固定不变。响应会在 languages_hinted 中回显规范化后的提示。
  • keyterm=<term> 可提高姓名、产品术语和行话的识别权重。它仅适用于 Nova-3 和 Flux STT；其他模型（例如 Nova-2）应改用 keywords。每个术语重复设置一次此参数。每个请求的所有 keyterm 总计最多为 500 个 token；超过上限会导致请求失败，并返回 Keyterm limit exceeded。Deepgram 建议远低于此上限，只使用 20 到 50 个重要术语。逗号、分号和 term:weight 不会导致请求被拒绝；API 会将整个值视为一个字面术语，因此你原本想提高权重的内容不会生效。
  • summarize=v2、sentiment=true、topics=true 和 intents=true 会添加音频智能功能。这些功能仅适用于预录制的英语音频。
  • 实时流式传输使用 wss://api.deepgram.com/v1/listen?model=nova-3、相同的 Authorization 标头和二进制音频帧。静音期间每隔 3 到 5 秒发送文本帧 {"type":"KeepAlive"}，如 keep-alive 页面所述；若 10 秒内没有音频或 KeepAlive，连接将以 NET-0001 关闭。结束时发送 {"type":"CloseStream"}。如需在流传输期间更改词汇或格式，请发送 {"type":"Configure","keyterms":["routing number"],"features":{"numerals":true}}：keyterms 会替换整个列表（包括 keyterm 查询参数；[] 会清空列表，省略或设为 null 则保留列表），且仅适用于 Nova-3 模型；features 可切换 numerals 等布尔选项。发送下一条配置前，请等待 ConfigureSuccess 或 ConfigureFailure；发生失败（CONFIGURE_KEYTERMS_NOT_SUPPORTED、CONFIGURE_KEYTERM_LIMIT_EXCEEDED、CONFIGURE_ALREADY_PENDING、CONFIGURE_INTERNAL_ERROR）时，该消息中的任何设置都不会生效，流仍会继续。区域主机使用相同路径和密钥：wss://api.eu.deepgram.com/v1/listen、wss://api.au.deepgram.com/v1/listen、wss://api.in.deepgram.com/v1/listen。

Flux STT：支持轮次检测的对话音频

通过 WebSocket 连接。Flux 没有 REST 接口。

wss://api.deepgram.com/v2/listen?model=flux-general-en&encoding=linear16&sample_rate=16000

发送相同的 Authorization: Token 标头。音频必须为单声道。对于原始音频（linear16、linear32、mulaw、alaw、opus、ogg-opus），必须提供 encoding 和 sample_rate；对于 WAV、Ogg 或 WebM 容器，两者都省略。每次发送 80 ms 的音频块。Flux STT 没有 KeepAlive 消息：WebSocket ping 会取代它，超时时间为 60 秒。如需在区域内处理，请使用 wss://api.eu.deepgram.com/v2/listen、wss://api.au.deepgram.com/v2/listen 或 wss://api.in.deepgram.com/v2/listen，并使用相同的密钥。

/v2/listen 上有两个值得注意的查询参数：

  • redact 接受 numbers 或 aggressive_numbers；任何其他值都会导致握手失败，并返回 400。每个被遮盖的片段都会变成一个 *，而不是 [REDACTED] 或实体标签。
  • profanity_filter=true 在 /v2/listen 上有效，包括 language=multi。

服务端会先发送 Connected，然后发送一系列 TurnInfo 消息。每条消息都包含 event、turn_index、transcript、带时间戳的 words，以及 end_of_turn_confidence。event 的取值如下：

  • Update：在一个轮次进行期间，大约每 0.25 s 的音频发送一次。
  • StartOfTurn：说话者开始讲话。用它来中断你的 Agent（抢话）。
  • EndOfTurn：说话者结束讲话。将转录文本发送给你的大模型。它包含 trigger，取值为 model、manual 或 timeout。
  • EagerEndOfTurn 和 TurnResumed：仅在设置了 eager_eot_threshold 时发送。收到第一个事件时开始起草回复；收到第二个事件时取消。EndOfTurn 的转录文本与 EagerEndOfTurn 的转录文本完全一致。预计大模型调用量会增加 50% 到 70%，以换取端到端延迟减少约 100 到 200 ms；建议先只使用 EndOfTurn。

以下三个查询参数可调整轮次检测，并且都可以通过下方的 Configure 消息在流传输期间更改：

参数范围默认值效果
eot_threshold0.5 到 1.00.7触发 EndOfTurn 所需的置信度。1.0 会禁用模型检测。
eager_eot_threshold0.3 到 0.9未设置启用 EagerEndOfTurn。值越低，触发越早，但误判也越多。必须小于或等于 eot_threshold。
eot_timeout_ms500 到 600005000无论置信度如何，达到此静音时长后都会触发 EndOfTurn。

客户端控制消息，每条都是一个 JSON 文本帧：

  • {"type":"Configure","thresholds":{"eot_threshold":0.8},"keyterms":["Deepgram"],"numerals":true} 可在不重新连接的情况下更改阈值、关键词、language_hints 或 numerals。
    • 结构和原子性：如示例所示，轮次检测阈值应放在 thresholds 下；省略的字段会保留原值。同一条消息中的所有字段会一并生效，或者均不生效：如果有一个字段未通过验证，则所有字段都不会生效。
    • keyterms：该数组会替换整个列表，最多包含 100 个纯文本词条（不支持 term:weight 语法）。
    • language_hints：[] 会清除提示并恢复自动检测；省略该字段或发送 null 则会保留现有提示。
    • numerals：以 numerals 查询参数的值为初始值，并应用于 Flux STT 处理更新后发送的转录文本，不会应用于已发送的转录文本。该值必须是 JSON 布尔值：字符串 "true" 无法通过架构验证，Flux STT 会返回代码为 UNPARSABLE_CLIENT_MESSAGE 的 Error，并关闭连接。
    • 回复为 ConfigureSuccess，其中会回显包括 numerals 在内的完整有效配置；或者为 ConfigureFailure，其中包含 code 和 description，指出被拒绝的字段，并保留之前的配置。
  • {"type":"ForceEndTurn"}（于 2026 年 8 月 28 日新增）会根据你自己的信号结束当前轮次，例如按键通话松开、DTMF 音调或发送按钮。Flux STT 会发出 "trigger":"manual" 的 EndOfTurn。如果当前没有活动轮次，则会忽略此消息，并返回代码为 FORCE_END_TURN_NO_ACTIVE_TURN 的 Warning。设置 eot_threshold=1.0 可完全由你控制每个轮次，并将 eot_timeout_ms 设为较高值作为后备机制（"trigger":"timeout"）。
    • SDK 方法：JS 5.9.0 sendForceEndTurn、Python 7.8.0 send_force_end_turn、Java 0.9.0 sendForceEndTurn、Go 3.8.0 ForceEndTurn()、Rust 0.10.1 force_end_turn()、.NET 7.1.0 的 SendForceEndTurn()，该方法位于具体的 FluxWebSocketClient 上，而非接口上。
  • {"type":"CloseStream"} 会完成对已接收音频的解码，发出对应的 Update 消息，并关闭连接，且不会带有 WebSocket 关闭状态码。它不会结束活动轮次：不会发出 EndOfTurn，因此最后一条消息是临时 Update。若要以最终转录文本结束，请先发送 ForceEndTurn，再发送 CloseStream；消息会按顺序处理，因此轮次会先结束，然后连接关闭。若顺序相反，ForceEndTurn 将不起作用。

对于非英语或混合语言通话，请使用 model=flux-general-multi，并可选择重复传入 language_hint=<code> 参数（例如 language_hint=en&language_hint=es）。不提供提示时，模型会自行检测语言。此时 TurnInfo 会包含 languages 和 languages_hinted。numerals 会格式化 flux-general-en 中的所有数字；对于 flux-general-multi，它会格式化英语、西班牙语、法语、德语、俄语、葡萄牙语、意大利语和荷兰语数字，而印地语和日语数字则保持口语形式。

常见错误

  1. Authorization: Bearer <api key> 会返回 401。API 密钥使用 Authorization: Token <key>。Bearer 仅用于 POST /v1/auth/grant 签发的短期 JWT。
  2. 对于拼错的模型名称，以及项目无权使用的真实模型，都会返回包含 {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."} 的 403 响应。响应正文中包含 request_id。申请访问权限前，请先检查名称是否拼写正确。GET https://api.deepgram.com/v1/models 会列出公开目录；GET /v1/projects/{project_id}/models 会列出项目可用的模型。不存在名为 nova-3-conversational 的模型；对话音频使用 Flux，即 flux-general-en。公开目录不会列出 Flux 模型名称，因此 Flux 文档是查询这些名称的依据。
  3. /v1/listen 不支持 Flux，model=flux 也不是有效值。请将 flux-general-en 或 flux-general-multi 与 /v2/listen 搭配使用。
  4. 在 Flux 中使用 language=en 或 language=multi 是错误的。模型名称会指定语言。在 /v2/listen 中，只有 flux-general-multi 接受 language_hint；在其他模型中使用会返回 400。
  5. 为容器化音频（WAV、Ogg、WebM）设置 encoding 或 sample_rate 会导致错误或输出乱码。请省略这两个参数，让容器声明格式。
  6. 在 /v1/listen 中使用 ForceEndTurn 会返回错误；该参数仅适用于 Flux。
  7. /v2/listen 不支持 smart_format、diarize 和 intelligence 参数。说话人标签和摘要属于 Nova 的工作。
  8. 作为二进制帧发送的 KeepAlive 会被错误处理。请将控制消息作为文本帧发送，将音频作为二进制帧发送。
  9. {"type":"Configure","features":{"numerals":true}} 是 /v1/listen 的写法。Flux STT 不接受 features 嵌套结构，并会关闭连接；在 /v2/listen 中，请将 numerals 作为顶层字段发送：{"type":"Configure","numerals":true}。

定价

Deepgram 按音频分钟数收取语音转文本费用。价格会变动，请访问 https://deepgram.com/pricing 查看，而不要依赖任何技能中的价格信息。

适合使用其他技能的情况

  • 需要查看每个参数、响应架构或消息字段：使用 api 技能，文件 references/listen.md。
  • 想查看某个主题的文档页面：使用 docs 技能。该技能参考的页面列在 Sources 下。
  • 想要一个带 UI 的可运行应用：使用 starters 技能（transcription、live-transcription 和 flux 功能）。
  • 想要一段少于 50 行、仅涵盖一个功能的代码片段：使用 recipes 技能，https://github.com/deepgram/recipes。
  • 想将 Deepgram 接入 Twilio、LiveKit、Pipecat、LangChain 或其他平台：使用 examples 技能。
  • 想要符合语言惯例的 SDK 代码：从相应的 SDK 仓库安装 Nova 对应的 deepgram-{js,python,java,go,rust,dotnet}-speech-to-text，以及 Flux STT 对应的 deepgram-{lang}-conversational-stt（依此类推，使用 npx skills add deepgram/deepgram-python-sdk）。
  • 想通过 SDK 在流中途使用 numerals：deepgram-{lang}-conversational-stt 技能未涵盖此功能，因此请参考本技能中 Configure 条目的消息格式。JavaScript SDK 从 5.13.0 版开始支持发送此消息（socket.sendConfigure({type:"Configure", numerals:true})），Python SDK 从 7.11.0 版开始支持（connection.send_configure(ListenV2Configure(numerals=True))），Java SDK 从 0.10.2 版开始支持（sendConfigure(ListenV2Configure.builder().numerals(true).build())），.NET SDK 从 7.2.0 版开始支持（在 Flux ConfigureSchema 上设置 Numerals）。
  • 想在 Go（最高至 3.10.0 版）或 Rust（最高至 0.14.0 版）SDK 中途使用 numerals：它们的 Flux Configure 类型不包含 numerals 字段，因此请发送原始 JSON Configure 消息，或在连接 URL 上设置 numerals。
  • 想通过 SDK 使用 Nova /v1/listen Configure 消息或 language_hint：JS 从 5.15.0 版开始支持 Configure，从 5.16.0 版开始支持 ConfigureSuccess、ConfigureFailure 和 language_hint；Python 从 7.13.0 版开始支持 Configure，从 7.14.0 版开始支持响应，从 7.15.0 版开始支持 language_hint；Java 从 0.11.1 版开始支持 Configure，从 0.11.2 版开始支持响应和 languageHint。.NET 7.2.0 版通过 SendConfigure 发送 Configure，但不对响应进行类型定义（其文档说明，拒绝请求会以 Error 形式返回），且不支持 /v1/listen language_hint。Go 和 Rust 均不支持这些功能，因此请发送原始 JSON，并自行将 language_hint 添加到 URL。
  • 想要分析结果，而不只是转录文本（/v1/listen 上的 summarize、sentiment、topics、intents、detect_entities）：使用 audio-intelligence 技能。对于已有文本，请使用 /v1/read 和 text-intelligence 技能。
  • 想要文本转语音或完整的语音 Agent：使用 text-to-speech 或 voice-agent 技能。
  • 想要 shell 命令，而不是应用程序代码：使用 cli 技能。
  • 想让你的编码工具能够查询文档：使用 setup-mcp 技能。

来源

评论

支持 Markdown