语音合成

本页介绍如何在 kapon 中，通过 火山方舟 Volc Ark 渠道 透传调用 Volcengine OpenSpeech 文本转语音（TTS）服务，包括：

V1 HTTP 非流式接口；
V3 HTTP 单向流式接口；
V3 长文本异步任务（submit/query）；
V1/V3 WebSocket 流式接口的路径约定与路由说明。

所有请求都经由 kapon 转发到 Volcengine OpenSpeech，不需要自行管理上游凭证（可选），只需在 Header 中携带 kapon API Key；平台会按需要将渠道配置中的 TTS 凭证注入上游请求头，保持请求体 / 响应体与官方文档协议完全一致。

export BASE_URL="https://models.kapon.cloud"
export TOKEN="oh-xxxxxxxxxxxxxxxx"

统一使用：

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 上游鉴权信息（可选）：

{
  "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. 安全性注意事项

客户端请求时使用的 kapon API Key：

Authorization: Bearer oh-xxxxxxxx

仅用于 kapon 的用户鉴权。转发到 OpenSpeech 上游时，平台会主动移除该 Header，确保 kapon Key 不会出现在 Volcengine 日志中。

三、V1 HTTP 非流式调用示例

V1 HTTP 非流式接口：一次性返回全部合成音频（base64 编码）。请求路径：

POST /volcark/openspeech/api/v1/tts?channel_id=<channel_id>

示例：

curl -X POST "$BASE_URL/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）。请求路径：

POST /volcark/openspeech/api/v3/tts/unidirectional?channel_id=<channel_id>

示例：

curl -N "$BASE_URL/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

请求路径：

POST /volcark/openspeech/api/v3/tts/submit?channel_id=<channel_id>

示例：

curl -X POST "$BASE_URL/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 }
        ]
      }
    }
  }'

返回示例（与官方一致）：

{
  "code": 20000000,
  "data": {
    "req_text_length": 11,
    "task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0",
    "task_status": 1
  },
  "message": "ok"
}

2. 查询任务 query

请求路径：

POST /volcark/openspeech/api/v3/tts/query?channel_id=<channel_id>

示例：

curl -X POST "$BASE_URL/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：1 Running、2 Success、3 Failure。

平台不会对这些字段做任何改写，可以直接按 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://models.kapon.cloud/volcark/openspeech/api/v1/tts/ws_binary?channel_id=<channel_id>
V3 单向流式：
wss://openspeech.bytedance.com/api/v3/tts/unidirectional/stream
→ wss://models.kapon.cloud/volcark/openspeech/api/v3/tts/unidirectional/stream?channel_id=<channel_id>
V3 双向流式：
wss://openspeech.bytedance.com/api/v3/tts/bidirection
→ wss://models.kapon.cloud/volcark/openspeech/api/v3/tts/bidirection?channel_id=<channel_id>

其他握手 Header 与请求/响应 payload 均与官方文档保持一致。

概述与使用

图片生成

视频生成

语音合成

一、接口总览

1. HTTP 接口

2. WebSocket 接口

二、渠道配置与 TTS 凭证注入

1. 渠道选择：channel_id

2. TTS 凭证配置：custom_parameter.tts

3. 安全性注意事项

三、V1 HTTP 非流式调用示例

四、V3 HTTP 单向流式调用示例

五、V3 长文本异步任务

1. 提交任务 submit

2. 查询任务 query

六、WebSocket 透传说明

概述与使用

图片生成

视频生成

语音合成

​一、接口总览

​1. HTTP 接口

​2. WebSocket 接口

​二、渠道配置与 TTS 凭证注入

​1. 渠道选择：channel_id

​2. TTS 凭证配置：custom_parameter.tts

​3. 安全性注意事项

​三、V1 HTTP 非流式调用示例

​四、V3 HTTP 单向流式调用示例

​五、V3 长文本异步任务

​1. 提交任务 submit

​2. 查询任务 query

​六、WebSocket 透传说明

一、接口总览

1. HTTP 接口

2. WebSocket 接口

二、渠道配置与 TTS 凭证注入

1. 渠道选择：channel_id

2. TTS 凭证配置：custom_parameter.tts

3. 安全性注意事项

三、V1 HTTP 非流式调用示例

四、V3 HTTP 单向流式调用示例

五、V3 长文本异步任务

1. 提交任务 submit

2. 查询任务 query

六、WebSocket 透传说明