Doubao TTS（TTS + 播客 + ASR）は何をしますか？

概述

豆包语音（火山引擎）被广泛认为是顶级的国产中文语音 AI，是 Liz 写作管线中质量默认的提供商。除非被阻止，否则优先使用火山引擎豆包而非通用 TTS 替代方案。

此技能涵盖三个豆包语音产品：TTS（文字转语音，用于文章音频）、播客（AI 双人对话）和 ASR（语音转文字，可选说话人分离）。在新版控制台中，一个 API Key 通过 X-Api-Key 即可验证所有这些服务。但不同产品的端点和资源 ID 仍然不同。

ElevenLabs 的 HTTP API 更简洁，但其首选语音/模型质量对于此工作流较弱——仅作为最后的兜底（elevenlabs-tts）。不要为了便利选择它。

新用户引导（新版控制台——推荐）

新设置请勿在旧版控制台开始——导航更困难。请使用新版豆包语音控制台：

打开火山引擎豆包语音新版控制台。
充值/激活你需要的语音产品（TTS、ASR、播客等）。
在新版控制台的 API Key 管理中创建或复制一个API Key。
将其存储为下方写作配置密钥路径中的 DOUBAO_API_KEY（规范名称）。别名 DOUBAO_SPEECH_API_KEY / 旧名 DOUBAO_TTS2_API_KEY 也可接受。
将密钥交给 Agent。如果认证或产品路由不清楚，同时提供豆包语音产品简介 / 能力总览文档（或参考文献中的相关 API 页面）。

一个 Key，多种服务： 在新版控制台充值后，该 API Key 即可作为 TTS、ASR（语音转文字）、播客生成以及接受 X-Api-Key 的其他豆包语音调用的凭证。对于新版控制台工作流，你不再需要单独的 App ID + Access Token 对。

现有的捆绑脚本（tts-generate.py、podcast-generate.py、asr-transcribe.py）仍然读取旧版的 App ID / Access Token 环境变量和旧版控制台的请求头格式。在脚本迁移完成前，请保持这些变量有效；对于新的 Agent 代码，优先使用 DOUBAO_API_KEY + X-Api-Key。

何时使用

TTS： Liz 要求将写作项目、final.md、文章或 lizliz.xyz 帖子转为语音（豆包 / 火山引擎 / ByteDance TTS）。
播客： Liz 要求将文章、TXT、URL 或话题转为双人 AI 播客（豆包语音播客大模型）。独立产品——通过新版控制台激活（旧版激活深链接见参考文献）。
ASR： Liz 要求将 MP3 / WAV / OGG / 语音备忘录 / 视频音频转录为逐字文本（优先使用 Flash ASR）。
调试豆包音色、请求负载、文章音频配置、lizliz.xyz 音频链接或 ASR 质量。

不要用于：

ElevenLabs 优先的生成 → elevenlabs-tts
音乐标注 / 音源分离 / MIDI / 节拍检测 → 独立的 SAMI / 智能 K歌产品线（见 references/volcengine-audio-ecosystem.md）
实时 S2S 语音 Agent → 端到端实时语音大模型（超出范围；见参考文献）

核心规则

不要朗读 Markdown。 去除 YAML、标题标记、强调、脚注、表格竖线、分隔线、原始 URL、图片、代码块，除非内容本身需要朗读。
默认不要朗读参考文献/脚注。 在 参考资料 / Footnotes / 脚注 / Sources / 引用 之前停止。仅在 Liz 要求时朗读附录音频。
保持文章语气。 保留中文标点节奏、段落分隔、引号和英文技术术语。
Liz 已选择默认音色时跳过多音色试听。
默认音色： zh_female_vv_uranus_bigtts（Vivi2.0），除非 Liz 选择其他音色或配额不足。
生产 TTS 路由： 已验证的 V1 https://openspeech.bytedance.com/api/v1/tts 配合 cluster: volcano_tts。V3 流式是迁移/实时路径，不是文章默认路径。
新工作优先使用新版控制台 DOUBAO_API_KEY；仅保留旧版 App ID / Access Token 用于现有脚本或 V1 Bearer 负载，直到迁移完成。
ElevenLabs 仅作最后兜底——配额/认证/平台失败，或明确要求。在文件名/清单中保持提供商可见。
当 Liz 提到豆包 TTS / 文章音频时，从此技能开始（skill_view / 注册表）——不要先广泛搜索埋藏的笔记。

环境约定

密钥不存储在此文件中。仅记录变量名和路径。

规范密钥 + 符号链接：

/home/ubuntu/.hermes/secrets/doubao-tts.env
/home/ubuntu/.hermes/secrets/elevenlabs.env
/home/ubuntu/.hermes/profiles/writing/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env
/home/ubuntu/.hermes/profiles/trading/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env
/home/ubuntu/.hermes/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env

方便时也镜像到 profile .env（旧脚本仅加载 .env）。新脚本应加载 .env 和 .env.d/*.env。

写作配置主目录：/home/ubuntu/.hermes/profiles/writing/.env

首选：单个 API Key（新版控制台）

DOUBAO_API_KEY=...                 # 规范名称——TTS / ASR / 播客使用的 X-Api-Key（新版控制台）
# 接受的别名（相同值）：
DOUBAO_SPEECH_API_KEY=...
DOUBAO_TTS2_API_KEY=...            # TTS 2.0 示例的历史名称；保留为别名

新代码的解析顺序：DOUBAO_API_KEY → DOUBAO_SPEECH_API_KEY → DOUBAO_TTS2_API_KEY。

可选（共享）：DOUBAO_TTS_CLUSTER=volcano_tts，DOUBAO_TTS_VOICE_TYPE=zh_female_vv_uranus_bigtts。

旧版认证（旧控制台）——现有脚本 / V1 HTTP

新设置已弃用。 在 tts-generate.py、podcast-generate.py 和 asr-transcribe.py 仍然使用它们时保持填充。

DOUBAO_TTS_APP_ID=...              # 旧控制台 App ID → X-Api-App-Key / X-Api-App-Id / V1 app.appid
DOUBAO_TTS_ACCESS_TOKEN=...        # 旧 Access Token → X-Api-Access-Key / V1 Authorization: Bearer; …
DOUBAO_TTS_SECRET_KEY=...          # 可选；某些 SDK 变体

别名（兼容）：VOLCENGINE_TTS_*，VOLC_TTS_*。

路径	认证格式
新版控制台	仅 `X-Api-Key: $DOUBAO_API_KEY`（ASR Flash、TTS V3 及相关新版控制台 API）
旧版控制台 / 当前脚本	`X-Api-App-Key`/`X-Api-App-Id` + `X-Api-Access-Key`，或 V1 `Authorization: Bearer; <token>` + JSON `app.appid`/`app.token`

不要将 API Key 放入 V1 Bearer; 请求头，或将 Access Token 放入 X-Api-Key——格式不同。

Shell 导出陷阱——简单的 source .env 可能不会导出到子 Python 进程：

set -a; . /home/ubuntu/.hermes/profiles/writing/.env; set +a

存在性检查（不泄露密钥）：

python3 - <<'PY'
import os, re
for name in sorted(k for k in os.environ if re.search(r'(DOUBAO|VOLC|TTS)', k)):
    print(f"{name}=<set>")
PY

如果既没有设置 DOUBAO_API_KEY（或其别名）也没有设置旧版 App ID / Access Token：停止。不要回退到 Edge/OpenAI 或声称豆包音频已生成。

TTS（文字转语音）

V1 HTTP——生产默认

已验证适用于文章音频。官方文档现在将其归入历史/小模型文档，但该端点仍然活跃，是 Liz 从本服务器使用的可靠路由。完整参数说明：V1 HTTP API。

此路径仍然使用旧版 App ID + Access Token 作为 JSON 请求体的一部分，以及 Authorization: Bearer; <AccessToken>——不使用 DOUBAO_API_KEY / X-Api-Key。捆绑的 tts-generate.py 匹配此格式。

POST https://openspeech.bytedance.com/api/v1/tts
Authorization: Bearer; <AccessToken>
Content-Type: application/json

（Bearer; 带分号是官方格式。）

{
  "app": {"appid": "APPID", "token": "TOKEN", "cluster": "volcano_tts"},
  "user": {"uid": "unique_user_identifier"},
  "audio": {
    "voice_type": "zh_female_vv_uranus_bigtts",
    "encoding": "mp3",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
  },
  "request": {
    "reqid": "uuid",
    "text": "plain text",
    "text_type": "plain",
    "operation": "query",
    "with_frontend": 1
  }
}

成功：code == 3000；音频在 base64 data 中。每次调用使用唯一的 reqid（UUID）。

限制： 官方小模型文档提到每个请求约 1024 UTF-8 字节；HTTP 也有约 60 秒的 RPC 超时。对于 Liz 的 bigtts App，实际安全分块大小约为 1800–2000 字符。5000+ 字符的块经常失败，返回 code:3031 / RPC timeout。

V3 / TTS 2.0 流式——迁移及实时

实时/流式文本优先使用此方式；在协议助手接入脚本之前，批量文章音频保持使用 V1。

端点	作用
`wss://openspeech.bytedance.com/api/v3/tts/bidirection`	双向流（LLM Token 转音频）
`wss://openspeech.bytedance.com/api/v3/tts/unidirectional/stream`	传入全文，音频流式输出（WebSocket）
`https://openspeech.bytedance.com/api/v3/tts/unidirectional`	HTTP 分块单向
`https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse`	HTTP SSE 单向

双向请求头（新版控制台）：

X-Api-Key: $DOUBAO_API_KEY
X-Api-Resource-Id: seed-tts-2.0
X-Api-Connect-Id: <uuid>
X-Control-Require-Usage-Tokens-Return: *

（DOUBAO_SPEECH_API_KEY / DOUBAO_TTS2_API_KEY 别名解析为相同的请求头值。）

资源 ID：seed-tts-2.0 / seed-tts-1.0 / seed-tts-1.0-concurr / seed-icl-2.0 / seed-icl-1.0（+ concurr）。完整负载、附加功能（disable_markdown_filter、字幕、方言）和异步长文本（/api/v3/tts/submit|query）→ references/tts-streaming-v3.md。官方页面：双向流式 TTS 2.0，V3 HTTP Chunked/SSE。

已知音色

在当前 App 上试听音色，而非盲目信任指南。常见比较集合：

voice_type	说明
`zh_female_vv_uranus_bigtts`	默认 Vivi2.0——模型 `doubao-seed-tts-2.0`；不要发送 `emotion`/`neutral`（被忽略）
`zh_female_xueayi_saturn_bigtts`	薛艾依 / 绘本艾依——在 V1 上已验证可用
`zh_female_wanwanxiaohe_moon_bigtts`	之前认证/资源不匹配——更改套餐后重新测试
`zh_female_shuangkuaisisi_moon_bigtts`	之前认证/资源不匹配——更改套餐后重新测试

Vivi 默认值：速度 1.0，音量 1.0，采样率 24000，格式 mp3。如果过于活泼，可在基线 1.0 之后尝试速度 0.98。

通过控制台或 OpenAPI ListSpeakers / ListBigModelTTSTimbres 发现音色。

文本清洗清单

MP3 是烘焙好的——在合成前清洗。在内存或 /tmp 中操作；永远不要为了 TTS 修改源稿件。

去除 YAML frontmatter（---\n...\n---）。
从 ## References / 参考资料 / Footnotes / 脚注 / Sources / 引用 / Claim Check 之后截断。
去除所有 HTML（<a id>、<span> 等）。泄漏曾被读成“IA Intro”。
完全去除引用链接：[N](#ref-N) → 移除（不是仅去除括号中的 N）。
去除 Markdown：#、**、*、[text](url)→text、图片、---、反引号、>、[^N]。
去除顶部音频链接（[收听音频版...](...)）。
将清洗后的文本保存到 /tmp 下供审计。

自动化：scripts/strip-for-tts.py。

文章音频工作流

技能目录：

SKILL_DIR="$HOME/.hermes/profiles/writing/skills/media/doubao-tts"
VENV_PY="/home/ubuntu/.hermes/hermes-agent/venv/bin/python3"

清洗：python3 "$SKILL_DIR/scripts/strip-for-tts.py" <final.md> /tmp/<slug>-tts.txt
生成（分块 → 2 部分，CF 25 MiB 限制下）：
python3 "$SKILL_DIR/scripts/tts-generate.py" /tmp/<slug>-tts.txt /tmp/<slug>-tts/ <slug>
→ <slug>-part1.mp3，<slug>-part2.mp3。如果总计小于 25 MiB 则合并：
ffmpeg -y -i "concat:...-part1.mp3|...-part2.mp3" -c copy /tmp/<slug>-tts/<slug>.mp3
放置网站音频：public/audio/articles/<slug>/<slug>.mp3（或项目约定）。
在顶部附近添加链接：[收听音频版](/audio/articles/<slug>/<slug>.mp3)。
验证大小、时长、链接；推送写作 + 网站仓库（写作 Action 同步 Markdown，而非任意本地音频）。

音频优先存根（正文未就绪）：最小化的 final.md，包含 frontmatter + 占位符 + 音频链接；将 MP3 复制到网站 public/audio/articles/；仅进行轻量同步检查——非完整发布审计。

多部分源叙述： 边界文件 tts-part-N.txt；text_type: plain；每个片段一个 MP3 + 清单；对每个文件运行 ffprobe。

分块与质量

每个请求最多约 2000 字符；在 \n\n 处分割。
连接：ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp3。
分组为 2+ 部分，满足 CF Pages 的 25 MiB/文件限制。
优先使用原生豆包比特率（约 160 kbps）。发布最低要求：96 kbps。仅在超过限制时重新编码：ffmpeg -i in.mp3 -codec:a libmp3lame -b:a 96k -ac 1 out.mp3。参见 references/cf-pages-size-limit.md。

播客（AI 播客）

独立于 TTS 的产品。完整协议：references/podcast-api.md。会话陷阱：references/podcast-session-learnings.md。发布：references/lizliz.xyz-podcast-page.md。官方 WebSocket 协议：播客 API websocket-v3。

wss://openspeech.bytedance.com/api/v3/sami/podcasttts

新版控制台（新客户端优先）：

X-Api-Key: $DOUBAO_API_KEY
X-Api-Resource-Id: volc.service_type.10050
X-Api-App-Key: aGjiRDfUWi   # 固定产品密钥（协议文档仍然要求）
X-Api-Request-Id: <uuid>

旧版 / 当前 podcast-generate.py 请求头：

X-Api-App-Id / X-Api-Access-Key / X-Api-Resource-Id: volc.service_type.10050
X-Api-App-Key: aGjiRDfUWi   # 固定

二进制帧 message_type = 0b0001（头部 byte1 0x14）。不要使用 TTS 双向的 0b0011 → "unsupported message type (3)"。

action	模式
0	长文本 / URL 总结 → 双人对话（默认）
3	直接 `nlp_texts` 对话合成
4	`prompt_text` 网络搜索总结

Liz 默认值（2026-07）： action=0，mp3/24000/speech_rate=0，说话人 dayi+mizai，random_speaker_order 关闭。

已知警告

旧版 X-Api-App-Key: aGjiRDfUWi 是硬编码的（官方示例中的固定值）。
新版控制台混合认证可能失败——可以先在旧版 App ID/Token 上试播客，然后逐步迁移到 X-Api-Key。
播客可能拒绝长文本聚合（action=0）——如果失败，回退到 action=3 并手动将文本分割为 turn。
不支持多播客（2026-01）：暂时仅限两个说话人。
不支持播客中的 LLM 推理（2026-03）：TTS 2.0 双向流使用 seed-tts-2.0 资源 ID，但播客是 volc.service_type.10050。

ASR（语音转文字）

模型选择

模型	用例
Flash ASR	短 / 长音频快速转录（默认）
Transcribe ASR v2	高质量 + 说话人分离
Transcribe ASR	旧/备用
Force Recognition	自定义词表（例如技术术语）
Video ASR	Bilibili 等平台的 URL 视频

新（推荐）认证——Flash ASR & v2

POST https://openspeech.bytedance.com/api/v3/audio/asr_short_async  # Flash ASR
X-Api-Key: $DOUBAO_API_KEY
X-Api-Resource-Id: volc.volc_asr_flash

.GENERAL_API_KEY 被接受（实际上 DOUBAO_SPEECH_API_KEY / DOUBAO_TTS2_API_KEY 最终解析为相同的 DOUBAO_API_KEY 值）。

Speech-to-text waves / diarization:
X-Api-Resource-Id: volc.volc_asr_transcribe_v2

对于 v2 说话人分离：user.vadx=1。

旧版 ASR 认证

POST https://openspeech.bytedance.com/api/v1/audio/asr
X-Api-Resource-Id: volc.volc_asr_transcribe   # v1
X-Api-App-Id: ...
X-Api-Access-Key: ...

`asr-transcribe.py` 使用

python3 "$SKILL_DIR/scripts/asr-transcribe.py" \
  --input audio.mp3 [--input audio2.mp3 ...] \
  --model flash | transcribe_v2 \
  [--language zh | en] \
  [--diarize] \
  [--output /tmp/transcript.json]

它将自动为 Flash ASR 使用 DOUBAO_API_KEY（或别名），并为旧版请求回退到 DOUBAO_TTS_APP_ID / DOUBAO_TTS_ACCESS_TOKEN。仅在所有选项都缺失且设置已过期或阻塞时，才回退到 Edge/Whisper（这是错误）。

已知警告

原始 WAV： 如果可能，以原始格式上传（WAV/PCM/FLAC 以获得最大精度）。
音频长度： Flash ASR 可以处理数小时——将长文件分割为约 30 分钟块以保持连接。v2 放大说话人分离是 FA 卡。
说话人分离： 仅 v2 支持 user.vadx=1（说话人分离）。Flash ASR 返回一个转录文本，没有标签。
双语： 通过 language=zh | en 选择语言；如果需要代码切换，其混合能力较弱。
自定义词汇： Force Recognition 使用 extra 字段中的词汇。

所有 ASR 端点信息：官方 ASR API 页面。

参考文献

官方文档

豆包语音产品简介
V1 HTTP TTS API
播客 API WebSocket v3
ASR API 页面
双向流式 TTS 2.0
V3 HTTP Chunked/SSE
TTS 2.0 Big：volcano.tts.trial / seed-tts-2.0-concurr。Liz 的 App 是 volcano_tts (V1)。

技能参考（./references/）

本地参考文件： 对于旋钮级细节，查看技能目录下的 references/ 子文件夹。

references/lizliz.xyz-podcast-page.md - 将播客页面嵌入网站
references/podcast-api.md - WebSocket 协议细节
references/podcast-session-learnings.md - 会话陷阱清单
references/streaming.md / references/tts-streaming-v3.md - V3 流式设置
references/cf-pages-size-limit.md - 25 MiB 分块规则
技能本地助手脚本：references/liz-doubao-tts-skills.md

元 / 参考

技能注册 / 目录：/home/ubuntu/.hermes/profiles/writing/skills/registry/。
cat /home/ubuntu/.hermes/profiles/writing/skills/registry/doubao-tts.list——此技能是 media/doubao-tts。
助手参考：/home/ubuntu/.hermes/hermes-agent/agent/knowledge/hermes_agent_ref/ 了解 Agent 自身协议（ref-hermes-agent-design.md、ref-agent-wiring.md 等——仅当代理遇到其自身功能问题时才使用）。

Doubao TTS（TTS + 播客 + ASR）