doubao-tts-cn

基于火山引擎豆包 V3 异步长文本语音合成接口，通过 Python 脚本把文本或 Markdown 文件合成为 mp3/wav/pcm/ogg_opus 音频，可设置音色、语速、音量、情感强度与 SSML，并可选输出字幕时间戳；附安装脚本与环境变量配置，适用于有声书、故事朗读与批量音频生产。

happyphper

热度 35.16

最近更新 2026-05-11 17:47:01

分类：创作依赖：代码执行 / 读写文件 / 第三方 API应用场景：故事创作 / 工作流 / 自动化脚本

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add doubao-tts-cn

Metadata

name: doubao-tts
version: 2.0.0
description: 将文本或 Markdown 文件合成为高质量语音音频，基于火山引擎（Volcengine） V3 异步长文本合成接口。支持情感设置、SSML 标记、字幕时间戳同步输出。适用于有声书制作、哄睡故事合成、批量音频生产等场景。当用户需要将文本转换为语音、TTS 合成、朗读文本时使用。
metadata: {"openclaw":{"requires":{"bins":["python3"],"env":["VOLCENGINE_APP_ID","VOLCENGINE_ACCESS_TOKEN"]},"primaryEnv":"VOLCENGINE_ACCESS_TOKEN"}}

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

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

前置条件

用户需要在火山引擎控制台开通语音合成服务
创建应用，获取 APP ID 和 Access Token
确保已配置 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 接口共享并发配额

配置说明

环境变量加载优先级：

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

错误处理

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

规则

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