Appearance
语音合成
通过 /volcark/openspeech/* 接口,在 Volc Ark 渠道下透传调用 Volcengine OpenSpeech 文本转语音(TTS)服务。
本页介绍如何在 Fhddos 中,通过 火山方舟 Volc Ark 渠道 透传调用 Volcengine OpenSpeech 文本转语音(TTS)服务,包括:
- V1 HTTP 非流式接口;
- V3 HTTP 单向流式接口;
- V3 长文本异步任务(submit/query);
- V1/V3 WebSocket 流式接口的路径约定与路由说明。
所有请求都经由 Fhddos 转发到 Volcengine OpenSpeech,不需要自行管理上游凭证(可选),只需在 Header 中携带 Fhddos API Key;平台会按需要将渠道配置中的 TTS 凭证注入上游请求头,保持请求体 / 响应体与官方文档协议完全一致。
bash
export BASE_URL="https://aiapi.fhddos.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"统一使用:
http
Authorization: Bearer <TOKEN>
Content-Type: application/json一、接口总览
所有 Volcengine TTS 接口均挂载在 VolcArk 路由组下,并要求通过 channel_id 指定一个火山方舟渠道:
1. HTTP 接口
V1 非流式(一次性返回整段音频)
POST /volcark/openspeech/api/v1/tts?channel_id=<channel_id>V3 HTTP 单向流式(JSON 流式返回)
POST /volcark/openspeech/api/v3/tts/unidirectional?channel_id=<channel_id>V3 长文本异步任务
- 提交任务:
POST /volcark/openspeech/api/v3/tts/submit?channel_id=<channel_id> - 查询任务:
POST /volcark/openspeech/api/v3/tts/query?channel_id=<channel_id>
- 提交任务:
2. WebSocket 接口
WebSocket 目前主要用于端到端集成测试与内部联调,协议完全透传官方二进制帧(不做解析)。
V1 单向流式(二进制协议)
GET /volcark/openspeech/api/v1/tts/ws_binary?channel_id=<channel_id>V3 WebSocket 单向流式
GET /volcark/openspeech/api/v3/tts/unidirectional/stream?channel_id=<channel_id>V3 WebSocket 双向流式
GET /volcark/openspeech/api/v3/tts/bidirection?channel_id=<channel_id>
二、渠道配置与 TTS 凭证注入
1. 渠道选择:channel_id
所有 TTS 接口都要求 query 参数 channel_id,用于明确选择一个 VolcArk 渠道:
- 渠道类型必须为
VolcArk(配置项ChannelTypeVolcArk,在前端显示为「火山方舟 Volc Ark」); - 渠道状态必须为启用;
- 若条件不满足,接口会直接返回 400。
2. TTS 凭证配置:custom_parameter.tts
在 VolcArk 渠道的 custom_parameter 字段中,可以按需配置 TTS 上游鉴权信息(可选):
json
{
"tts": {
"v1": {
"token": "<v1_access_token>"
},
"v3": {
"app_id": "<X-Api-App-Id>",
"access_key": "<X-Api-Access-Key>",
"resource_id": "seed-tts-1.1"
}
}
}含义:
tts.v1.token- 用于 V1 HTTP / WebSocket 接口;
- 若调用方请求头中未显式设置
Authorization,平台会自动设置:Authorization: Bearer;<token>
tts.v3.app_id/tts.v3.access_key/tts.v3.resource_id- 用于 V3 系列接口(HTTP + WebSocket);
- 若请求头中未显式设置对应字段,平台会自动注入:
X-Api-App-Id: <app_id>X-Api-Access-Key: <access_key>X-Api-Resource-Id: <resource_id>
如果你不希望在渠道层面配置这些字段,也可以在调用时直接按照 Volcengine 官方文档,将对应 Header 与 JSON 字段补齐;平台不会覆盖你手动设置的头部。
3. 安全性注意事项
客户端请求时使用的 Fhddos API Key:
http
Authorization: Bearer oh-xxxxxxxx仅用于 Fhddos 的用户鉴权。转发到 OpenSpeech 上游时,平台会主动移除该 Header,确保 Fhddos Key 不会出现在 Volcengine 日志中。
三、V1 HTTP 非流式调用示例
V1 HTTP 非流式接口:一次性返回全部合成音频(base64 编码)。
请求路径:
bash
POST /volcark/openspeech/api/v1/tts?channel_id=<channel_id>示例:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/openspeech/api/v1/tts?channel_id=123" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"app": {
"appid": "appid123",
"token": "any_non_empty_string",
"cluster": "volcano_tts"
},
"user": {
"uid": "uid123"
},
"audio": {
"voice_type": "zh_male_M392_conversation_wvae_bigtts",
"encoding": "mp3",
"speed_ratio": 1.0
},
"request": {
"reqid": "uuid",
"text": "字节跳动语音合成",
"operation": "query"
}
}'说明:
- 请求体字段与官方文档完全一致;
- 若渠道配置了
tts.v1.token,平台会为上游请求自动补全Authorization: Bearer;<token>; - 响应中的 JSON 与官方一致(含
code/message/data/sequence/addition等),其中音频数据为 base64 编码。
四、V3 HTTP 单向流式调用示例
V3 HTTP 单向流式接口:服务端以 JSON 流式返回多个片段,每个片段包含一段音频片段(同样为 base64)。
请求路径:
bash
POST /volcark/openspeech/api/v3/tts/unidirectional?channel_id=<channel_id>示例:
bash
curl -N "https://aiapi.fhddos.com/volcark/openspeech/api/v3/tts/unidirectional?channel_id=123" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Control-Require-Usage-Tokens-Return: text_words" \
-d '{
"user": {
"uid": "12345"
},
"req_params": {
"text": "你好,我是火山引擎的语音合成服务。这是一个美好的旅程。",
"speaker": "zh_female_shuangkuaisisi_moon_bigtts",
"audio_params": {
"format": "mp3",
"sample_rate": 24000
}
}
}'说明:
X-Control-Require-Usage-Tokens-Return可选,若设置,在合成结束时会返回usage字段(例如text_words表示计费字符数);- 平台不会改写响应体,仅在 Header 中透传
X-Tt-Logid方便排查; - 若渠道配置了
tts.v3,平台会自动注入 V3 鉴权头;否则你需要在请求头中自行设置对应字段。
五、V3 长文本异步任务
1. 提交任务 submit
请求路径:
bash
POST /volcark/openspeech/api/v3/tts/submit?channel_id=<channel_id>示例:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/openspeech/api/v3/tts/submit?channel_id=123" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user": {
"uid": "12345"
},
"unique_id": "5dad8cff-aa5d-496d-a83e-e9c902f4d460",
"req_params": {
"text": "明朝开国皇帝朱元璋也称这本书为,万物之根",
"speaker": "custom_mix_bigtts",
"audio_params": {
"format": "mp3",
"sample_rate": 24000
},
"mix_speaker": {
"speakers": [
{ "source_speaker": "zh_male_bvlazysheep", "mix_factor": 0.3 },
{ "source_speaker": "BV120_streaming", "mix_factor": 0.3 },
{ "source_speaker": "zh_male_ahu_conversation_wvae_bigtts", "mix_factor": 0.4 }
]
}
}
}'返回示例(与官方一致):
json
{
"code": 20000000,
"data": {
"req_text_length": 11,
"task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0",
"task_status": 1
},
"message": "ok"
}2. 查询任务 query
请求路径:
bash
POST /volcark/openspeech/api/v3/tts/query?channel_id=<channel_id>示例:
bash
curl -X POST "https://aiapi.fhddos.com/volcark/openspeech/api/v3/tts/query?channel_id=123" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0"
}'成功完成时,返回内容与官方一致,例如包含:
audio_url:音频下载地址(带有限时签名);sentences:句级/字级时间戳信息;req_text_length/synthesize_text_length;task_status:1Running、2Success、3Failure。
平台不会对这些字段做任何改写,可以直接按 Volcengine 文档解析使用。
六、WebSocket 透传说明
对于 WebSocket 接口,平台采用“字节级透明代理”模式:
- 建连阶段:
- 使用
channel_id选择 VolcArk 渠道; - 根据
custom_parameter.tts.v1/v3注入必要的鉴权头; - 通过
wss://openspeech.bytedance.com/...发起上游连接;
- 使用
- 数据转发阶段:
- 基于
common/requester.WSProxy双向转发 WebSocket 帧; - 不解析 TTS 的二进制协议头(包括
Protocol version/Message type/event/payload等); - 不修改任何音频或文本内容;
- 若上游或客户端断开连接,平台会同时关闭另一端。
- 基于
这意味着你可以直接使用 Volcengine 官方 WebSocket 示例代码,只需将域名与路径替换为:
- V1:
wss://openspeech.bytedance.com/api/v1/tts/ws_binary
→wss://aiapi.fhddos.com/volcark/openspeech/api/v1/tts/ws_binary?channel_id=<channel_id> - V3 单向流式:
wss://openspeech.bytedance.com/api/v3/tts/unidirectional/stream
→wss://aiapi.fhddos.com/volcark/openspeech/api/v3/tts/unidirectional/stream?channel_id=<channel_id> - V3 双向流式:
wss://openspeech.bytedance.com/api/v3/tts/bidirection
→wss://aiapi.fhddos.com/volcark/openspeech/api/v3/tts/bidirection?channel_id=<channel_id>
其他握手 Header 与请求/响应 payload 均与官方文档保持一致。