starters

Deepgram 入门应用

克隆一个可运行的演示，然后开始构建。每个入门项目都是一个最小化、可运行的应用，你可以在此基础上扩展。

1. 选择你的功能

你想构建什么？

• 转写文件 → transcription — 发送音频/视频，返回文本（REST、Nova）
• 转写实时流 → live-transcription — 实时语音转文本（WebSocket、Nova）
• 生成语音 → text-to-speech — 发送文本，返回音频（REST、Aura）
• 流式生成语音 → live-text-to-speech — 实时文本转音频（WebSocket、Aura）
• 分析文本 → text-intelligence — 对你已有的文本进行情感、主题、意图、摘要分析 （REST、/v1/read）
• 构建语音 Agent → voice-agent — 对话式 AI Agent（WebSocket、agent.deepgram.com）
• 带轮次检测的对话式 STT → flux — 用于语音 Agent 和交互式助手的 Deepgram Flux STT（WebSocket、/v2/listen）
• 用于语音 Agent 的轮次式 TTS → flux-tts — Deepgram Flux TTS，支持打断的流式合成（WebSocket、/v2/speak）

没有音频智能入门项目。 text-intelligence 仅支持文本 — 它把你已有的文本发送到 /v1/read。在 deepgram-starters 中，任何框架都不存在 {framework}-audio-intelligence 仓库，所以不要构造这些 URL。要对音频运行智能功能（摘要、情感、主题、意图），它们是 /v1/listen 上的查询参数，而不是单独的入门项目：克隆你的框架对应的 transcription 入门项目，并把参数添加到它现有的请求中。关于 /v1/listen 支持哪些功能，请参阅 api skill。

用于语音转文本的 Nova 与 Flux STT： 对通用转写、字幕和批量工作负载，请使用 transcription 或 live-transcription（Nova、/v1/listen）。当你需要对对话音频使用内置轮次检测时，请使用 flux（Flux STT、/v2/listen）。完整对比请参阅 api skill。

用于文本转语音的 Aura 与 Flux TTS： 对一次性合成、非英语语音和压缩音频，请使用 text-to-speech 或 live-text-to-speech（Aura、/v1/speak）。当你把大模型输出流式传输到扬声器并需要轮次生命周期和打断时，请使用 flux-tts（Flux TTS、/v2/speak）。完整对比请参阅 api skill。

Flux TTS 入门项目仅适用于 node、flask、fastapi、django 和 java — 这些是 Deepgram 在 Flux TTS 模板应用 官方发布的五个应用。其他框架没有 flux-tts 入门项目；不要构造这些 URL。对于不受支持的框架，请从 api skill 的 Flux TTS 部分和各个 SDK skill 开始。

2. 选择你的技术栈

语言	框架
JavaScript	node
TypeScript	bun、deno
Python	fastapi、flask、django
Go	go
Java	java
C#	csharp
Rust	rust
Ruby	ruby
PHP	php
C++	cpp

3. 克隆并运行

每个 starter 都位于 https://github.com/deepgram-starters/{framework}-{feature} —— 框架 在前，功能在后。克隆时要带子模块；每个 starter 都引入了两个 git 子模块 —— 其 浏览器前端位于 frontend/，共享的 starter 契约位于 contracts/ —— 而普通的 git clone 会让这两个目录都为空，应用无法运行：

git clone --recurse-submodules https://github.com/deepgram-starters/{framework}-{feature}.git
cd {framework}-{feature}

在 96 个 starter 中，有 80 个的 .gitmodules 里两个子模块 URL 都是 SSH（[email protected]:...）， 尽管这两个仓库都是公开的，所以除非用户拥有 GitHub SSH 密钥，否则 --recurse-submodules 会失败并报 Host key verification failed。其余 16 个使用 HTTPS URL，无需密钥即可克隆：13 个 {framework}-live-transcription starter 中的 12 个（除 rust-live-transcription 外的每一个），加上 csharp-voice-agent、django-voice-agent、flask-voice-agent 和 node-voice-agent。没有 SSH 密钥时，克隆前要把 SSH 改写为 HTTPS。这种改写 对那 16 个 HTTPS starter 没有任何影响，因此可以安全地用于每一个 starter：

git -c url."https://github.com/".insteadOf="[email protected]:" \
  clone --recurse-submodules https://github.com/deepgram-starters/{framework}-{feature}.git

starter 自带的 make init 会运行 git submodule update --init --recursive 并安装 依赖，但它会沿用 .gitmodules 中的 URL。在那 80 个 SSH starter 上，没有密钥时它会 以同样的方式失败，所以它是给已配置好 SSH 的用户（或那 16 个 HTTPS starter 之一）使用的路径，而不是给未配置 SSH 的用户的变通方案。

设置你的 API key，并按照 README 操作：

export DEEPGRAM_API_KEY=your_key_here

在 https://console.deepgram.com 获取 API key。

或者用 CLI 脚手架

Deepgram CLI 有一个脚手架工具，可以为你找到并克隆一个 starter：

dg init --list                       # browse templates
dg init --list --search python       # filter
dg init node-transcription           # clone into ./node-transcription
dg init node-transcription --dir ./my-app

dg init 并不能解决子模块问题。 它运行的是普通克隆，因此 frontend/ 和 contracts/ 会是空的，但它仍然会打印 Done! … is ready 和 "status": "success"。加上 --install 会运行 starter 的 make check-prereqs && make init，这会碰到同样的 .gitmodules URL：在那 80 个 SSH starter 上它会失败并报 Host key verification failed，而 dg init 无论如何 都会报告成功。没有 GitHub SSH 密钥时，在 dg init 之后手动完成检出：

cd my-app
git -c url."https://github.com/".insteadOf="[email protected]:" \
  submodule update --init --recursive

dg init 还被标记为 alpha，而且它的模板库与下面的矩阵是两份不同的列表， 而不是矩阵的子集。它带有 44 个模板，没有 flux 或 flux-tts 条目； 它仍然列出 sinatra-transcription，而该仓库已归档且为私有，因此对 Deepgram 之外的任何人 克隆都会返回 404；它还列出了 nextjs-* 模板，而这些模板现在会从 deepgram-starters 重定向到 deepgram-devs，这就是下面没有 nextjs 行的原因。请以矩阵为准， 并回退到 git clone。安装 deepctl 以及 dg init 的其余内容，请参阅 cli skill。

{feature}-html 仓库不是起始模板

deepgram-starters 组织还包含 transcription-html、live-transcription-html、 text-to-speech-html、live-text-to-speech-html、text-intelligence-html、voice-agent-html、 flux-html 和 flux-tts-html。不要克隆这些仓库，也不要将它们作为起始模板提供。 每一个 都是共享的浏览器前端，由某个后端起始模板作为其 frontend/ 子模块引入 —— node-transcription 引入 transcription-html，flask-voice-agent 引入 voice-agent-html， node-flux-tts 和 java-flux-tts 都引入 flux-tts-html，依此类推。这八个仓库中有七个 在自己的 README 中说明了这一点（"This is a frontend submodule - do not use directly"）；flux-tts-html 没有这样的警告，但同样是以这种方式被引入的。它们都不提供 API，因此都不能 独立运行。改为克隆后端起始模板，相应的前端会随之而来。

它们还颠倒了命名规则。起始模板的模式是 {framework}-{feature}，但这些是 {feature}-html —— 而镜像名称并不存在，所以不要自行构造： deepgram-starters/html-transcription 是 404。矩阵中没有 vanilla-HTML 这一行， 因为不存在独立的浏览器起始模板；对于纯浏览器的工作，克隆你想要的功能对应的 node 起始模板， 然后阅读其 frontend/ 目录。

示例

"I want to build a voice agent in Python" → git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-voice-agent.git

"I need live transcription in my Node app" → git clone --recurse-submodules https://github.com/deepgram-starters/node-live-transcription.git

"I want to add text-to-speech to my Go service" → git clone --recurse-submodules https://github.com/deepgram-starters/go-text-to-speech.git

"I want to analyze audio for sentiment in C#" → git clone --recurse-submodules https://github.com/deepgram-starters/csharp-text-intelligence.git

"I want streaming TTS with barge-in for my Node voice agent" → git clone --recurse-submodules https://github.com/deepgram-starters/node-flux-tts.git

"I want a plain browser/HTML demo" → 没有独立的 HTML 起始模板。克隆 node-{feature} 并在其 frontend/ 目录中工作 —— 那就是 {feature}-html 子模块所包含的同一份浏览器代码。

所有起始模板

下面的每个 URL 都是真实、已发布、未归档的仓库,并且该表是完整的 集合：13 个框架 × 7 个功能，外加五个框架拥有的 flux-tts。某个单元格 显示 — 表示该起始模板不存在；不要构造该 URL。

java-flux-tts 的 README 使用普通的 git clone 克隆，不带 --recurse-submodules，而 其 .gitmodules 将两个子模块都指向 SSH URL，因此按照其 Maven 步骤操作会留下 空的 frontend/ 和 contracts/。请改用第 3 节中的克隆命令。

	transcription	live-transcription	text-to-speech	live-text-to-speech	text-intelligence	voice-agent	flux	flux-tts
node	repo	repo	repo	repo	repo	repo	repo	repo
bun	repo	repo	repo	repo	repo	repo	repo	—
deno	repo	repo	repo	repo	repo	repo	repo	—
fastapi	repo	repo	repo	repo	repo	repo	repo	repo
flask	repo	repo	repo	repo	repo	repo	repo	repo
django	repo	repo	repo	repo	repo	repo	repo	repo
go	repo	repo	repo	repo	repo	repo	repo	—
java	repo	repo	repo	repo	repo	repo	repo	repo
csharp	repo	repo	repo	repo	repo	repo	repo	—
rust	repo	repo	repo	repo	repo	repo	repo	—
ruby	repo	repo	repo	repo	repo	repo	repo	—
php	repo	repo	repo	repo	repo	repo	repo	—
cpp	repo	repo	repo	repo	repo	repo	repo	—

需要更具体的内容？

• 聚焦的功能代码片段（一个功能、一种语言，< 50 行） → recipes 技能 → https://github.com/deepgram/recipes
• 第三方集成（Twilio、LiveKit、LangChain、Vercel AI SDK、Discord 等） → examples 技能 → https://github.com/deepgram/examples
• SDK 专用代码技能（地道导入、异步模式、注意事项） → npx skills add deepgram/deepgram-{lang}-sdk — 查看 api 技能，了解技能可公开安装的 6 个 SDK。

相关 Deepgram 技能

• api：整合后的 REST + WebSocket API 参考
• recipes：每种语言的最小可运行功能代码片段
• examples：与第三方平台的完整集成示例
• docs：文档查找器
• cli：deepctl，包括用于从终端搭建模板的 dg init
• setup-mcp：Deepgram MCP 服务安装