> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 语音合成

> 通过 /volcark/openspeech/* 接口，在 Volc Ark 渠道下透传调用 Volcengine OpenSpeech 文本转语音（TTS）服务。

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

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

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

```bash theme={null}
export BASE_URL="https://models.hingnet.com.cn"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

统一使用：

```http theme={null}
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 theme={null}
{
  "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. 安全性注意事项

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

```http theme={null}
Authorization: Bearer oh-xxxxxxxx
```

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

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

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

请求路径：

```bash theme={null}
POST /volcark/openspeech/api/v1/tts?channel_id=<channel_id>
```

示例：

```bash theme={null}
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）。

请求路径：

```bash theme={null}
POST /volcark/openspeech/api/v3/tts/unidirectional?channel_id=<channel_id>
```

示例：

```bash theme={null}
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

请求路径：

```bash theme={null}
POST /volcark/openspeech/api/v3/tts/submit?channel_id=<channel_id>
```

示例：

```bash theme={null}
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 }
        ]
      }
    }
  }'
```

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

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

### 2. 查询任务 query

请求路径：

```bash theme={null}
POST /volcark/openspeech/api/v3/tts/query?channel_id=<channel_id>
```

示例：

```bash theme={null}
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.hingnet.com.cn/volcark/openspeech/api/v1/tts/ws_binary?channel_id=<channel_id>`
* V3 单向流式：\
  `wss://openspeech.bytedance.com/api/v3/tts/unidirectional/stream`\
  → `wss://models.hingnet.com.cn/volcark/openspeech/api/v3/tts/unidirectional/stream?channel_id=<channel_id>`
* V3 双向流式：\
  `wss://openspeech.bytedance.com/api/v3/tts/bidirection`\
  → `wss://models.hingnet.com.cn/volcark/openspeech/api/v3/tts/bidirection?channel_id=<channel_id>`

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