单向流式API为用户提供文本转语音的能力，支持多语种、多方言，同时支持http协议流式输出。
1.1最佳实践
- 客户端读取服务端流式返回的json数据，从中取出对应的音频数据；
- 音频数据返回的是base64格式，需要解析后拼接到字节数组即可组装音频进行播放；
- 可以使用对应编程语言的连接复用组件，避免重复建立tcp连接（火山服务端keep-alive时间为1分钟），例如python的session组件：
session = requests.Session() response = session.post(url, headers=headers, json=payload, stream=True)
2.1 请求Request
请求路径
- 服务对应的请求路径：https://openspeech.bytedance.com/api/v3/tts/unidirectional
Request Headers
Key | 说明 | 是否必须 | Value示例 |
|---|---|---|---|
X-Api-App-Id | 使用火山引擎控制台获取的APP ID，可参考 控制台使用FAQ-Q1 | 是 | 123456789 |
X-Api-Access-Key | 使用火山引擎控制台获取的Access Token，可参考 控制台使用FAQ-Q1 | 是 | your-access-key |
X-Api-Resource-Id | 表示调用服务的资源信息 ID
| 是 |
（不支持声音复刻1.0） |
X-Api-App-Key | 固定值 | 是 | aGjiRDfUWi |
X-Api-Request-Id | 标识客户端请求ID，uuid随机字符串 | 否 | 67ee89ba-7050-4c04-a3d7-ac61a63499b3 |
Response Headers
Key | 说明 | Value示例 |
|---|---|---|
X-Tt-Logid | 服务端返回的 logid，建议用户获取和打印方便定位问题 | 2025041513355271DF5CF1A0AE0508E78C |
2.2 请求Body
字段 | 描述 | 是否必须 | 类型 | 默认值 |
|---|---|---|---|---|
user | 用户信息 | 否 | object | —— |
user.id | 用户uid | 否 | string | —— |
req_params.text | 输入文本（单向流式目前不支持ssml） | 是 | string | —— |
req_params.speaker | 发音人，具体见发音人列表 | 是 | string | —— |
req_params.audio_params | 音频参数，便于服务节省音频解码耗时 | 是 | object | —— |
req_params.audio_params.format | 音频编码格式，mp3/ogg_opus/pcm | 否 | string | mp3 |
req_params.audio_params.sample_rate | 音频采样率，可选值 [8000,16000,22050,24000,32000,44100,48000] | 否 | number | 24000 |
req_params.audio_params.BitRate | 音频比特率，可传16000、32000等。需另传additions = fmt.Sprintf("{"disable_default_bit_rate":true}")方可生效。 | 否 | number | —— |
req_params.audio_params.emotion | 设置音色的情感。示例："emotion": "angry" | 否 | string | —— |
req_params.audio_params.emotion_scale | 调用emotion设置情感参数后可使用emotion_scale进一步设置情绪值，范围1~5，不设置时默认值为4。 | 否 | number | 4 |
req_params.audio_params.speech_rate | 语速，取值范围[-50,100]，100代表2.0倍速，-50代表0.5倍数 | 否 | number | 0 |
req_params.audio_params.loudness_rate | 音量，取值范围[-50,100]，100代表2.0倍音量，-50代表0.5倍音量（mix音色暂不支持） | 否 | number | 0 |
req_params.audio_params.pitch_rate | 支持复刻和mix音色，需要在additions里传参，并且要在post_process里设置，音调取值范围[-12,12]。举例： | 否 | number | 0 |
req_params.audio_params.enable_timestamp | 是否选择同时返回字与音素时间戳 | 否 | bool | flase |
req_params.extra.silence_duration | 设置该参数可在句尾增加静音时长，范围0~30000ms。（注：增加的句尾静音主要针对传入文本最后的句尾，而非每句话的句尾） | 否 | number | 0 |
req_params.additions | 用户自定义参数 | 是 | jsonstring | —— |
additions结构定义
字段 | 描述 | 是否必须 | 类型 | 默认值 |
|---|---|---|---|---|
enable_language_detector | 自动识别语种 | 否 | bool | false |
disable_markdown_filter | 是否开启markdown解析过滤， | 否 | bool | false |
enable_latex_tn | 是否可以播报latex公式，需将disable_markdown_filter设为true | 否 | bool | false |
max_length_to_filter_parenthesis | 是否过滤括号内的部分，0为不过滤，100为过滤 | 否 | int | 100 |
explicit_language（明确语种） | 仅读指定语种的文本
示例（go）：additions = fmt.Sprintf("{"explicit_language": "zh"}") | 否 | string | —— |
context_language（参考语种） | 给模型提供参考的语种
| 否 | string | —— |
示例json
{ "req_params": { "text": "音频文件能够正常播放", "speaker": "zh_female_gaolengyujie_moon_bigtts", "additions": "{\"disable_markdown_filter\":true,\"enable_language_detector\":true,\"enable_latex_tn\":true,\"disable_default_bit_rate\":true,\"max_length_to_filter_parenthesis\":0,\"cache_config\":{\"text_type\":1,\"use_cache\":true}}", "audio_params": { "format": "mp3", "sample_rate": 24000 } } }
2.3 响应Response
- 音频响应数据，其中data对应合成音频base64音频数据：
{ "code": 0, "message": "", "data" : {{STRING}} }
- 合成音频结束对应的成功响应：
{ "code": 20000000, "message": "ok", "data": null }
Code | Message | 说明 |
|---|---|---|
20000000 | ok | 音频合成结束的成功状态码 |
40402003 | TTSExceededTextLimit:exceed max limit | 提交文本长度超过限制 |
45000000 | speaker permission denied: get resource id: access denied | 音色鉴权失败，一般是speaker指定音色未授权或者错误导致 |
quota exceeded for types: concurrency | 并发限流，一般是请求并发数超过限制 | |
55000000 | 服务端一些error | 服务端通用错误 |
Python：
