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

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

前置条件#

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

安装#

bash

bash {baseDir}/install.sh

非交互模式：

bash

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

使用方式#

基础合成#

bash

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

合成 Markdown 文件#

bash

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

指定音色和输出#

bash

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

启用字幕时间戳#

bash

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

设置情感#

bash

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

使用 SSML（仅模型 1.0）#

bash

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

完整参数组合#

bash

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音色 IDzh_female_chancan_v2_h5--format, -f音频格式 mp3/wav/pcm/ogg_opusmp3--sample-rate采样率24000--output, -o输出文件路径自动生成--ssml文本格式为 SSML（仅模型 1.0）false--emotion情感设置 happy/sad/angry 等无--emotion-scale情绪强度 1~54--subtitle启用字幕时间戳false--speed语速 [-50,100]0--volume音量 [-50,100]0--model模型版本 1.0/2.01.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