V2 双向流式合成（WebSocket）

本接口用于把持续到达的文本实时转换为语音。服务端会自动缓冲文本、识别句子边界，并以 JSON 消息连续返回十六进制音频分片。

适用于 AI Agent、实时客服、对话机器人和边生成边播放等场景。

SDK 下载位置

Java：下载 v1.0.2 ZIP · 查看源码

Python：下载 v1.0.2 ZIP · 查看源码

Go：下载 v1.0.2 ZIP · 查看源码

以上链接均为 MyVocal 官方 GitHub Release。安装和运行要求请查看对应 SDK 的 README.md。

1. 连接信息

连接地址：

wss://openapi.myvocal.ai
/v2/ai/speech/websocket

实际连接时请移除上方换行，使用页面顶部展示的完整地址。

API-Key

类型：string

必填：是

位置：WebSocket 握手 Header

功能：MyVocal API Key

安全要求：不要写入日志或客户端源码

当前接口仅支持：

模型：Skyblight-Turbo

并发线路：dedicated_concurrency

2. 消息流程

建立连接，收到 connected_success

发送 task_start

收到 task_started

多次发送 task_continue

接收句子事件和音频分片

可发送 task_flush 立即处理缓冲文本

发送 task_finish

收到 task_finished

服务端使用 Close Code 1000 正常关闭

三种完成信号含义不同：

is_final=true：当前音频请求的最后一个分片

sentence_end：当前句子的音频已全部返回

task_finished：整个会话结束

3. 启动任务

连接成功后发送 task_start：

{
  "event": "task_start",
  "model": "Skyblight-Turbo",
  "voice": "YOUR_VOICE_ID",
  "language": "en",
  "format": "mp3",
  "sample_rate": 32000,
  "bitrate": 128000,
  "channel": 1,
  "priority": "dedicated_concurrency",
  "voice_setting": {
    "speed": 1.0,
    "vol": 1.0,
    "pitch": 0,
    "emotion": "calm"
  },
  "subtitle_enable": true,
  "subtitle_type": "word_streaming",
  "session_id": "client-session-001"
}

3.1 基础参数

event

类型：string

必填：是

固定值：task_start

功能：启动一个语音合成会话

收到 task_started 后才能继续发送文本。

model

类型：string

必填：是

可选值：仅 Skyblight-Turbo

功能：指定语音合成模型

voice

类型：string

必填：是

功能：指定 MyVocal 音色 ID

即使使用 timbre_weights，当前接口仍要求提供有效的 voice。

language

类型：string

必填：否

示例：zh、en、ja

默认行为：不传时自动识别

功能：帮助模型选择正确的发音规则

format

类型：string

必填：否

默认值：mp3

可选值：mp3、pcm、wav、flac、pcmu_raw、pcmu_wav

功能：指定音频编码或容器

pcmu_raw 和 pcmu_wav 为 8 kHz G.711 mu-law。

sample_rate

类型：integer

必填：否

默认值：32000

可选值：8000、16000、22050、24000、32000、44100

单位：Hz

bitrate

类型：integer

必填：否

默认值：128000

可选值：32000、64000、128000、256000

单位：bit/s

生效条件：仅对 format=mp3 生效

channel

类型：integer

必填：否

默认值：1

可选值：1 或 2

功能：1 为单声道，2 为双声道

priority

类型：string

必填：是

可选值：仅 dedicated_concurrency

功能：使用独享并发线路

session_id

类型：string

必填：否

功能：由客户端标识并关联本次会话

服务端会在返回消息中原样回传。

3.2 voice_setting

voice_setting.speed

类型：number

必填：否

默认值：1.0

建议范围：0.5 至 2.0

功能：控制语速，数值越大语速越快

voice_setting.vol

类型：number

必填：否

默认值：1.0

建议范围：大于 0，不超过 10

功能：控制输出音量

voice_setting.pitch

类型：integer

必填：否

默认值：0

建议范围：-12 至 12

功能：调整基础音高，负值更低，正值更高

voice_setting.emotion

类型：string

必填：否

可选值：happy、sad、angry、fearful

可选值：disgusted、surprised、calm

功能：指定表达情绪

默认行为：不传时由模型根据文本自动选择

voice_setting.english_normalization

类型：boolean

必填：否

默认值：false

功能：提高数字等内容的英文朗读效果

注意：开启后可能略微增加延迟

voice_setting.latex_read

类型：boolean

必填：否

默认值：false

功能：开启 LaTeX 公式朗读

语言限制：仅用于中文

公式需使用 $$...$$ 包裹，并正确转义反斜杠。

建议客户端按上述范围做本地校验，不依赖服务端对越界值的兼容行为。

3.3 发音词典

pronunciation_dict.tone

类型：string[]

必填：否

功能：指定词语、缩写或符号的自定义读法

格式：原文/读法

示例：MyVocal/My Vocal

3.4 混合音色

{
  "voice": "PRIMARY_VOICE_ID",
  "timbre_weights": [
    {
      "voice_id": "VOICE_ID_A",
      "weight": 50
    },
    {
      "voice_id": "VOICE_ID_B",
      "weight": 50
    }
  ]
}

timbre_weights

类型：object[]

必填：否

功能：混合多个音色

数量限制：最多 4 个

当前接口仍要求顶层 voice 为有效音色 ID。

timbre_weights[].voice_id

类型：string

必填：是

功能：指定参与混合的音色 ID

timbre_weights[].weight

类型：integer

必填：是

范围：1 至 100

功能：数值越大，该音色特征占比越高

3.5 音色效果

voice_modify 建议只与 format=mp3 一起使用。

voice_modify.pitch

类型：integer

必填：否

范围：-100 至 100

功能：负值更低沉，正值更明亮

voice_modify.intensity

类型：integer

必填：否

范围：-100 至 100

功能：负值更有力，正值更柔和

voice_modify.timbre

类型：integer

必填：否

范围：-100 至 100

功能：负值更饱满，正值更清亮

voice_modify.sound_effects

类型：string

必填：否

可选值：spacious_echo、auditorium_echo

可选值：lofi_telephone、robotic

功能：应用一种声音效果

限制：一次只能选择一个

3.6 字幕参数

subtitle_enable

类型：boolean

必填：否

默认值：false

功能：在音频返回中附带字幕时间信息

subtitle_type

类型：string

必填：否

默认值：sentence

可选值：sentence、word、word_streaming

功能：选择句级、词级或流式词级时间戳

4. 持续发送文本

收到 task_started 后，可多次发送：

{
  "event": "task_continue",
  "text": "Hello, welcome to MyVocal."
}

event

类型：string

必填：是

固定值：task_continue

text

类型：string

必填：是

功能：追加到服务端缓冲区的文本

限制：单条消息不超过 10,000 个字符

建议保留句号、问号、感叹号和换行。明确的句末标点可以更快触发自然的句子级合成。

短文本没有句末标点时，可发送 task_flush。

5. 中断、刷新与结束

中断当前合成

{
  "event": "task_cancel"
}

服务端返回 task_canceled。连接仍可继续使用。

刷新缓冲区

{
  "event": "task_flush"
}

服务端处理当前缓冲文本后返回 task_flushed。会话保持可用，空缓冲区也允许发送。

结束整个会话

{
  "event": "task_finish"
}

服务端先处理剩余文本，再返回 task_finished，最后使用 Close Code 1000 正常关闭连接。

6. 服务端事件

connected_success

WebSocket 连接建立成功。客户端随后发送 task_start。

task_started

合成任务启动成功。客户端可以开始发送 task_continue。

sentence_start

一个缓冲句子开始合成，可用于句子级状态展示。

task_continued

返回音频分片及可选字幕和统计信息。客户端按到达顺序拼接 data.audio。

sentence_end

当前句子的音频已返回完成，不代表整个会话结束。

task_canceled

当前合成已中断，可继续发送新的 task_continue。

task_flushed

当前缓冲文本已处理完成，会话保持可用。

task_finished

整个会话已完成。客户端等待服务端 Close Code 1000。

task_failed

本次任务失败。客户端读取 error_code、error 和 base_resp，停止当前任务并按错误类型处理。

7. 音频和字幕响应

event

当前事件类型。

data.audio

类型：string

内容：十六进制编码的音频分片

处理：解码为 bytes，并按消息到达顺序拼接

data.subtitle.text

当前字幕文本。

data.subtitle.text_begin

当前字幕在文本中的起始位置。

data.subtitle.text_end

当前字幕在文本中的结束位置。

data.subtitle.time_begin

当前字幕在音频中的起始时间。

data.subtitle.time_end

当前字幕在音频中的结束时间。

data.subtitle.timestamped_words[]

词级字幕列表。每项可能包含：

word：词或字符内容

word_begin：文本起始位置

word_end：文本结束位置

time_begin：音频起始时间

time_end：音频结束时间

is_final

是否为当前音频请求的最后一个分片。

8. 会话、统计和错误响应

session_id

会话 ID。传入自定义值时会原样回传。

connect_id

当前 WebSocket 连接 ID。

trace_id

单次请求追踪 ID，可用于故障排查。

extra_info.audio_length

音频时长，单位毫秒。

extra_info.audio_sample_rate

实际音频采样率。

extra_info.audio_size

音频大小，单位字节。

extra_info.bitrate

实际音频码率。

extra_info.audio_format

实际音频格式。

extra_info.audio_channel

实际声道数。

extra_info.invisible_character_ratio

输入中不可见或无效字符的比例。比例过高时可能拒绝合成。

extra_info.usage_characters

本次合成计费用字符数。

extra_info.word_count

本次朗读的有效字符或词数量，不含标点。

base_resp.status_code

业务状态码，0 表示成功。

base_resp.status_msg

业务状态说明。

error_code

MyVocal 错误码，仅失败事件返回。

error

MyVocal 错误说明，仅失败事件返回。

9. 音频返回示例

{
  "event": "task_continued",
  "data": {
    "audio": "fff3..."
  },
  "is_final": false,
  "session_id": "client-session-001",
  "extra_info": {
    "audio_sample_rate": 32000,
    "audio_format": "mp3",
    "usage_characters": 28
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

10. 失败返回示例

{
  "event": "task_failed",
  "error_code": "400100",
  "error": "请求参数无效",
  "base_resp": {
    "status_code": 2013,
    "status_msg": "invalid params"
  }
}

11. 当前兼容性说明

当前不要传 continuous_sound

当前不要使用 format=opus

voice_modify 建议只用于 format=mp3

单条文本超过 10,000 个字符时返回 2204

收到 task_started 后不要再次发送 task_start

客户端应实现标准 Ping/Pong、读写超时和可控重连

不要依赖固定秒数判断连接一定存活或断开

1. 连接信息#

2. 消息流程#

3. 启动任务#

3.1 基础参数#

3.2 voice_setting#

3.3 发音词典#

3.4 混合音色#

3.5 音色效果#

3.6 字幕参数#

4. 持续发送文本#

5. 中断、刷新与结束#

中断当前合成#

刷新缓冲区#

结束整个会话#

6. 服务端事件#

7. 音频和字幕响应#

8. 会话、统计和错误响应#

9. 音频返回示例#

10. 失败返回示例#

11. 当前兼容性说明#

请求参数

1. 连接信息

2. 消息流程

3. 启动任务

3.1 基础参数

3.2 voice_setting

3.3 发音词典

3.4 混合音色

3.5 音色效果

3.6 字幕参数

4. 持续发送文本

5. 中断、刷新与结束

中断当前合成

刷新缓冲区

结束整个会话

6. 服务端事件

7. 音频和字幕响应

8. 会话、统计和错误响应

9. 音频返回示例

10. 失败返回示例

11. 当前兼容性说明