doubao-tts-cn

将文本或 Markdown 文件合成为高质量语音音频，基于火山引擎（Volcengine） V3 异步长文本合成接口。支持情感设置、SSML 标记、字幕时间戳同步输出。 适用于有声书制作、哄睡故事合成、批量音频生产等场景。 当用户需要将文本转换为语音、TTS 合成、朗读文本时使用。

豆包 TTS - 火山引擎语音合成 (V3 API)

将文本或 Markdown 文件合成为高质量语音音频，支持异步长文本合成（最高 10 万字符）。

前置条件

1. 用户需要在火山引擎控制台开通语音合成服务
2. 创建应用，获取 APP ID 和 Access Token
3. 确保已配置 VOLCENGINE_APP_ID 和 VOLCENGINE_ACCESS_TOKEN 环境变量

安装

bash {baseDir}/install.sh

非交互模式：

bash {baseDir}/install.sh --app-id <your_app_id> --access-token <your_access_token>

使用方式

基础合成

python3 {baseDir}/scripts/tts.py "你好，这是一段测试文本"

合成 Markdown 文件

python3 {baseDir}/scripts/tts.py "<markdown_file_path>"

指定音色和输出

python3 {baseDir}/scripts/tts.py "<file_or_text>" --voice-type BV700_streaming --output story.mp3

启用字幕时间戳

python3 {baseDir}/scripts/tts.py "<file_or_text>" --subtitle

设置情感

python3 {baseDir}/scripts/tts.py "<file_or_text>" --emotion happy --emotion-scale 4

使用 SSML（仅模型 1.0）

python3 {baseDir}/scripts/tts.py "<file_or_text>" --ssml --model 1.0

完整参数组合

python3 {baseDir}/scripts/tts.py story.md \
  --voice-type zh_female_chancan_v2_h5 \
  --format mp3 \
  --sample-rate 24000 \
  --output story.mp3 \
  --subtitle \
  --emotion happy \
  --model 1.0

参数说明：

参数	说明	默认值
input	文本内容或文件路径（必填）	-
--voice-type, -v	音色 ID	zh_female_chancan_v2_h5
--format, -f	音频格式 mp3/wav/pcm/ogg_opus	mp3
--sample-rate	采样率	24000
--output, -o	输出文件路径	自动生成
--ssml	文本格式为 SSML（仅模型 1.0）	false
--emotion	情感设置 happy/sad/angry 等	无
--emotion-scale	情绪强度 1~5	4
--subtitle	启用字幕时间戳	false
--speed	语速 [-50,100]	0
--volume	音量 [-50,100]	0
--model	模型版本 1.0/2.0	1.0
--timeout	最长等待秒数	1800

API 版本说明

本 Skill 使用 V3 API（/api/v3/tts/submit + /api/v3/tts/query），鉴权通过以下 Header：

• X-Api-App-Id: 应用 ID
• X-Api-Access-Key: Access Token
• X-Api-Resource-Id: 资源 ID（模型 1.0 用 seed-tts-1.0，模型 2.0 用 seed-tts-2.0）

注意事项

• 模型 2.0 暂不支持 SSML
• SSML 闭合标签内字符数不能超过 150 个
• 合成音频在服务端保存 7 天，下载链接有效期 1 小时
• submit 和 query 接口共享并发配额

配置说明

环境变量加载优先级：

1. 全局配置: ~/.config/doubao-tts/.env
2. 项目目录: 当前工作目录下的 .env
3. 系统环境变量

错误处理

错误码	说明
20000000	成功
40000000	请求参数错误
40000001	任务不存在或已过期
45000000	音色鉴权失败或并发限流
55000000	服务端错误

规则

• 始终通过 {baseDir} 引用脚本路径
• 合成前确认环境变量已配置
• 首次使用前需运行 bash {baseDir}/install.sh