类别：provider

Volcengine 语音合成 TTS

验证

mkdir -p output/volcengine-ai-audio-tts
python -m py_compile skills/ai/audio/volcengine-ai-audio-tts/scripts/generate_tts.py && echo "py_compile_ok" > output/volcengine-ai-audio-tts/validate.txt

通过标准：命令退出码为 0，且生成文件 output/volcengine-ai-audio-tts/validate.txt。

输出与证据

• 将生成的音频文件、请求载荷（request payload）及响应元数据保存至 output/volcengine-ai-audio-tts/ 目录下。
• 每次执行仅保留一份验证日志。

前置条件

• Python 3.8+；无需额外 SDK（仅依赖 requests 及 Python 标准库）。
• 安装命令：pip install requests
• 设置环境变量（来自 Volcengine 豆包语音控制台）：
  • VOLCENGINE_TTS_APP_ID — 应用 ID
  • VOLCENGINE_TTS_TOKEN — 应用 Token（用于 Authorization: Bearer ${token}）
  • VOLCENGINE_TTS_CLUSTER — 业务集群，例如 volcano_tts（标准音色）

可选：在仓库根目录或脚本所在目录中使用 .env 文件；脚本会自动加载其中的环境变量。

标准化接口（tts.generate）

请求参数

• text（字符串，必填）— 合成文本，UTF-8 编码，单次建议 ≤1024 字节
• voice_type（字符串，必填）— 音色，参见“发音人参数列表”，例如 BV700_streaming
• encoding（字符串，可选）— 编码格式：pcm | wav | mp3 | ogg_opus，默认为 mp3
• rate（整数，可选）— 采样率，支持 8000 / 16000 / 24000，默认为 24000
• speed_ratio（浮点数，可选）— 语速范围 [0.2, 3]，默认为 1.0
• volume_ratio（浮点数，可选）— 音量范围 [0.1, 3]，默认为 1.0
• pitch_ratio（浮点数，可选）— 音高范围 [0.1, 3]，默认为 1.0
• language（字符串，可选）— 语言标识，例如 cn

响应字段

• audio_path（字符串）— 音频文件在本地保存的路径
• sample_rate（整数）
• format（字符串）
• duration_ms（字符串，API 返回时提供）
• code（整数）— 返回值 3000 表示成功

快速开始（Python 脚本）

# 使用内联 JSON 请求
python skills/ai/audio/volcengine-ai-audio-tts/scripts/generate_tts.py 
  --request '{"text":"你好，这是一段测试语音。","voice_type":"BV700_streaming"}' 
  --output output/volcengine-ai-audio-tts/audio/out.mp3

# 使用请求文件
python skills/ai/audio/volcengine-ai-audio-tts/scripts/generate_tts.py 
  --file request.json 
  --output output/volcengine-ai-audio-tts/audio/out.wav 
  --print-response

运行指导

• 每次请求的 reqid 必须唯一；脚本内部使用 UUID 生成。
• 长文本请分段多次调用，或改用异步长文本合成接口。
• 所选音色与 cluster 值需与 Volcengine 控制台配置保持一致；复刻音色场景下，请将 speaker id 作为 voice_type 传入。
• 如遇 HTTP 429 错误，请降低并发请求数或增加请求间隔。

输出路径

• 默认输出目录：output/volcengine-ai-audio-tts/audio/
• 可通过环境变量 OUTPUT_DIR 覆盖基础输出路径。

工作流程

1. 确认用户意图、待合成文本、目标音色及期望输出格式。
2. 执行一次最小化请求，验证凭证（credentials）、cluster 及 voice_type 配置是否正确。
3. 使用显式参数执行目标语音合成任务。
4. 校验合成结果，并保存输出文件与相关证据文件。

参考文档

• references/api_reference.md — 请求/响应参数定义与错误码说明
• 在线语音合成 API - HTTP 一次性合成
• 参数基本说明
• 发音人参数列表
• 资料来源清单：references/sources.md