本 API 提供 实时语音合成（Text-to-Speech） 的 WebSocket 接口，适用于实时对话、IVR、客服机器人、游戏语音、AI Agent 多轮对话等场景。

WebSocket 通道提供：

超低延迟流式语音生成

多轮对话（单连接多段文本）

稳定高并发调度（priority = dedicated_concurrency）

Base64 / Binary 音频流

# 1. WebSocket Endpoint

节点 1：系统自动选择（推荐）

系统将根据网络状况与负载自动选择最优节点

wss://api.voicelibrary.co/enterprise/v1/tts/{voice_id}/websocket

节点 2：美国（US）

wss://api.us.voicelibrary.co/enterprise/v1/tts/{voice_id}/websocket

节点 3：爱尔兰（EU）

wss://api.eu.voicelibrary.co/enterprise/v1/tts/{voice_id}/websocket

节点 4：日本（JP）

wss://api.jp.voicelibrary.co/enterprise/v1/tts/{voice_id}/websocket

连接时必须携带 Query 参数（握手阶段决定模型、权限、音频格式等）。

# 2. Query Parameters（握手参数）

参数	类型	必填	说明
`model_id`	string	✅	使用的 TTS 模型 ID
`priority`	string	✅	必须为 `dedicated_concurrency`
`idleTimeout`	number	可选	最大 180 秒，无请求自动断开
`language_code`	string	可选	`zh`, `en`, `ja`, …
`format`	string	可选	`pcm_16000`, `pcm_8000`, `mp3`
`Timestamps`	boolean	可选	返回分词时间戳
`directStreaming`	boolean	可选	使用二进制音频输出

示例（推荐配置）

# 3. Authentication

连接 WebSocket 后，需在 Header 中加入：

api-key: <Your_API_Key>

示例（Java）：

# 4. Connection Flow（流程）

建立 WebSocket 连接

客户端发送 初始化消息（Initialization Message）

客户端发送文本

服务端持续返回 Base64 / binary 音频

收到 isFinal=true 时代表一段音频生成结束

客户端可继续发送下一段文本（单连接多轮）

关闭连接（可提前 flush）

# 5. Initialization Message（必须发送）

连接成功后必须发送一次初始化消息，否则不会开始生成。

{
  "text": " ",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75
  },
  "generation_config": {
    "synthesisSchedule": [120,160,250,290]
  }
}

说明：generation_config.synthesisSchedule（流式触发节奏）

该参数控制 WebSocket 合成过程的首包延迟与后续 chunk 输出节奏。

系统会在文本累计到一定字符数时触发音频生成。默认：

synthesisSchedule = [120, 160, 250, 290]

表示：

文本达到 120 字符 → 输出第一个音频分片（最低延迟）

达到 160 字符 → 输出第二个分片

达到 250 字符 → 输出第三个分片

达到 290 字符 → 输出第四个分片

📌 该参数的影响

数值较小	数值较大
延迟更低（更快听到声音）	延迟更高（需要更多文本上下文）
质量可能略低	质量更平滑、自然、情绪更一致

# 6. Text Request（文本合成请求）

格式：

{
  "text": "hello world",
  "earlyGeneration": false
}

字段说明：

字段	类型	说明
`text`	string	输入文本
`earlyGeneration`	boolean	若为 true，服务端会更早开始合成

文本需要 JSON escape

# 7. End Signal（结束或 flush）

模式 A：正常结束（进入下一段文本）

{"text": ""}

模式 B：强制 flush（立即结束当前段）

{"text": "", "flush": true}

flush=true 会立即触发 isFinal = true 的最后一个数据包。

# 8. Service Response（服务端返回）

服务端会多次返回 JSON：

{
  "audio": "/+MYxAAA....", // Base64 encoded audio
  "isFinal": false
}

或二进制帧（若 directStreaming=true）。

当：

"isFinal": true

时，表示当前文本的音频已生成完成，应存档或播放。

# 9. Multi-turn TTS（单连接多轮对话）

一个 WebSocket 可以处理 多段文本，流程：

connect → initialization → text1 → isFinal → text2 → isFinal → text3 → isFinal → close

返回 isFinal: null 且伴随音频数据，表示当前轮次的语音合成未显式结束（no isFinal: true），但 WebSocket 连接仍然保持可用状态，因此客户端可以在同一连接中继续发送下一段 text，无需等待明确的结束信号。

等价工程理解：

isFinal: null → 未显式结束，但不是错误，也不是阻塞态连接未关闭 = 可以继续写

每段音频会保存为独立文件。

# 10. Binary Audio Frames（可选模式）

将 directStreaming=true 时：

服务端会发送 Binary Frame (opcode 0x2)

客户端在 onMessage(ByteBuffer bytes) 中读取原始音频

Demo 已正确处理：

# 11. Connection Keep-alive（Ping/Pong 机制）

本 API 属于 服务端驱动的心跳结构。
因此：

✅ 客户端不需要主动发送 Ping

✅ 客户端只需自动回复 Pong（SDK 默认处理）

❌ 不要用定时器主动 sendPing() —— 可能会造成异常断链

服务端会在必要时发送 Ping。

# 12. Idle Timeout（连接空闲超时）

由握手参数 idleTimeout 控制

单位：秒

最大值：180 秒

若超过 idleTimeout 秒未收到新文本请求，服务器会自动断开连接

# 13. Error Handling（错误处理）

常见错误响应：

{
  "error": "service_error",
  "message": "An error occurred while processing your request"
}

错误类型说明：

错误码	说明	建议
`service_error`	内部错误	可重试
`unauthorized`	API Key 无效	检查 Header
`model_not_found`	模型不存在	确保 model_id 正确
`policy_violation`	控制帧异常（如过度 ping）	移除自定义 ping

# 14. Best Practices（实践建议）

✔ 使用单连接多轮对话

减少握手延迟，显著提高吞吐率。

✔ 避免主动发 Ping

由服务端负责。

✔ 每段文本结束后发送 EndSignal

保证音频完整性。

✔ 音频尽早写入文件并 reset buffer

防止内存累积。

单线程全双工通信(WebSocket)

# 1. WebSocket Endpoint

节点 1：系统自动选择（推荐）

节点 2：美国（US）

节点 3：爱尔兰（EU）

节点 4：日本（JP）

# 2. Query Parameters（握手参数）

示例（推荐配置）

# 3. Authentication

# 4. Connection Flow（流程）

# 5. Initialization Message（必须发送）

# 6. Text Request（文本合成请求）

格式：

文本需要 JSON escape

# 7. End Signal（结束或 flush）

模式 A：正常结束（进入下一段文本）

模式 B：强制 flush（立即结束当前段）

# 8. Service Response（服务端返回）

# 9. Multi-turn TTS（单连接多轮对话）

# 10. Binary Audio Frames（可选模式）

# 11. Connection Keep-alive（Ping/Pong 机制）

✅ 客户端不需要主动发送 Ping

✅ 客户端只需自动回复 Pong（SDK 默认处理）

❌ 不要用定时器主动 sendPing() —— 可能会造成异常断链

# 12. Idle Timeout（连接空闲超时）

# 13. Error Handling（错误处理）

# 14. Best Practices（实践建议）

✔ 使用单连接多轮对话

✔ 避免主动发 Ping

✔ 每段文本结束后发送 EndSignal

✔ 音频尽早写入文件并 reset buffer

请求参数

单线程全双工通信(WebSocket)

# 1. WebSocket Endpoint#

节点 1：系统自动选择（推荐）#

节点 2：美国（US）#

节点 3：爱尔兰（EU）#

节点 4：日本（JP）#

# 2. Query Parameters（握手参数）#

示例（推荐配置）#

# 3. Authentication#

# 4. Connection Flow（流程）#

# 5. Initialization Message（必须发送）#

# 6. Text Request（文本合成请求）#

格式：#

文本需要 JSON escape#

# 7. End Signal（结束或 flush）#

模式 A：正常结束（进入下一段文本）#

模式 B：强制 flush（立即结束当前段）#

# 8. Service Response（服务端返回）#

# 9. Multi-turn TTS（单连接多轮对话）#

# 10. Binary Audio Frames（可选模式）#

# 11. Connection Keep-alive（Ping/Pong 机制）#

✅ 客户端不需要主动发送 Ping#

✅ 客户端只需自动回复 Pong（SDK 默认处理）#

❌ 不要用定时器主动 sendPing() —— 可能会造成异常断链#

# 12. Idle Timeout（连接空闲超时）#

# 13. Error Handling（错误处理）#

# 14. Best Practices（实践建议）#

✔ 使用单连接多轮对话#

✔ 避免主动发 Ping#

✔ 每段文本结束后发送 EndSignal#

✔ 音频尽早写入文件并 reset buffer#

请求参数

# 1. WebSocket Endpoint

节点 1：系统自动选择（推荐）

节点 2：美国（US）

节点 3：爱尔兰（EU）

节点 4：日本（JP）

# 2. Query Parameters（握手参数）

示例（推荐配置）

# 3. Authentication

# 4. Connection Flow（流程）

# 5. Initialization Message（必须发送）

# 6. Text Request（文本合成请求）

格式：

文本需要 JSON escape

# 7. End Signal（结束或 flush）

模式 A：正常结束（进入下一段文本）

模式 B：强制 flush（立即结束当前段）

# 8. Service Response（服务端返回）

# 9. Multi-turn TTS（单连接多轮对话）

# 10. Binary Audio Frames（可选模式）

# 11. Connection Keep-alive（Ping/Pong 机制）

✅ 客户端不需要主动发送 Ping

✅ 客户端只需自动回复 Pong（SDK 默认处理）

❌ 不要用定时器主动 sendPing() —— 可能会造成异常断链

# 12. Idle Timeout（连接空闲超时）

# 13. Error Handling（错误处理）

# 14. Best Practices（实践建议）

✔ 使用单连接多轮对话

✔ 避免主动发 Ping

✔ 每段文本结束后发送 EndSignal

✔ 音频尽早写入文件并 reset buffer