多角色对话 · 多 Context - MyVocal AI语音大模型API文档

在一条连接中管理独立 Context，每个 Context 可以使用一个或多个音色。适合多角色对白，也适合 V4 / V3 Turbo 的单音色流式输入。

支持模型：myvocal_v3（默认）、myvocal_v4、myvocal_v3_turbo。

接入准备：企业 api-key、可用音色，以及 priority=dedicated_concurrency。

最小交互流程

建立连接 → 注册音色并发送 inputs → 接收音频 → close_context → 等待 is_final → close_socket

连接示例（握手 Header：api-key: YOUR_API_KEY）：

wss://api.voicelibrary.co/enterprise/v1/text-to-dialogue/websocket/multi?model_id=myvocal_v4&priority=dedicated_concurrency&format=mp3_128

创建 Context 并发送一句文本：

{"context_id":"demo","voices":["YOUR_VOICE_ID"],"inputs":[{"text":"你好，欢迎使用语音合成。","voice_id":"YOUR_VOICE_ID","new_turn":true}]}

结束该 Context：

{"context_id":"demo","close_context":true}

按 context_id 接收 Base64 音频，等待 is_final=true。所有任务完成后发送 {"close_socket":true}，等待连接正常关闭。也可用 close_socket 一次结束所有 Context。

与普通 TTS 多 Context 的区别

本接口发送 inputs，close_context 会处理剩余文本，无需提前 flush。普通 TTS 多 Context 使用不同的消息与结束流程。

模型选择

模型特点见模型介绍，完整语言代码见支持语言。

1. 连接信息

连接地址：

wss://api.voicelibrary.co/enterprise/v1/text-to-dialogue/websocket/multi

握手 Header：

api-key

类型：string

必填：是

位置：WebSocket 握手 Header

功能：MyVocal 企业 API Key

安全要求：不要写入客户端源码、日志或公开仓库

当前接口支持：

模型：myvocal_v3（默认）、myvocal_v4、myvocal_v3_turbo

并发线路：dedicated_concurrency

2. Query 参数

推荐连接示例：

?priority=dedicated_concurrency
&model_id=myvocal_v3
&format=mp3_128
&language_code=en
&timestamps=true
&text_normalization=auto
&seed=618021
&enable_logging=true

实际连接时请把 Query 参数放在同一行。

priority

类型：string

必填：是

可选值：仅 dedicated_concurrency

功能：使用独享并发线路

model_id

类型：string

必填：否

默认值：myvocal_v3

可选值：myvocal_v3、myvocal_v4、myvocal_v3_turbo

功能：指定当前连接使用的对话合成模型；切换模型需新建连接

format

类型：string

必填：否

默认值：mp3_128

功能：指定返回音频编码、采样率和 MP3 码率

可选值：

MP3：mp3_64、mp3_96、mp3_128、mp3_192

PCM：pcm_8000、pcm_16000、pcm_22050、pcm_24000、
pcm_44100

G.711 μ-law：ulaw_8000

需要精确按 turn 切分音频时，建议使用 PCM；MP3 的音频分片边界可能与 turn 边界不完全一致。

language_code

类型：string

必填：否，省略时根据输入文本选择语言

格式：模型支持的两位或三位语言代码，例如普通话 zh、英语 en、粤语 yue、菲律宾语 fil

位置：连接 URL 的 query，作用于该连接

功能：指定文本语言与发音；请提供对应语言的文本，此参数不用于翻译

myvocal_v4 与 myvocal_v3_turbo 支持相同的 94 种输出语言，包括普通话 zh、粤语 yue、英语 en、日语 ja 和韩语 ko。完整语言及代码见输出语言。

timestamps

类型：boolean

必填：否

默认值：false

功能：设为 true 时，在音频消息中返回字符时间信息

text_normalization

类型：string

必填：否

默认值：on

可选值：auto、on、off

功能：控制数字、日期、缩写等文本的朗读规范化

取值说明：

auto：由系统判断是否规范化

on：始终启用规范化

off：不启用规范化

seed

类型：integer

必填：否

范围：1 至 4294967295

功能：用于提升相同文本和配置下生成结果的一致性

相同 seed 会尽量生成相近的声音效果，但不保证音频字节完全一致。不传时
系统会自动选择新的 seed。

enable_logging

类型：boolean

必填：否

默认值：true

功能：控制本次请求是否保留生成历史

设为 false 时，本次请求使用不保留历史的处理方式，相关历史功能不可用。
该能力是否可用取决于企业账户配置。

3. 消息流程

建立 WebSocket 连接。

发送某个 context_id 的第一条消息，注册音色和可选设置。

持续发送 inputs。

接收带对应 context_id 的音频分片。

可使用 flush 立即处理当前缓冲文本。

使用 close_context 结束单个 context。

使用 close_socket 结束全部 context 和整个连接。

正常结束时服务端发送 WebSocket Close Code 1000。

4. 创建 Context

某个 context_id 的第一条消息必须包含 voices：

{
  "context_id": "scene-001",
  "voices": [
    "YOUR_VOICE_ID_A",
    "YOUR_VOICE_ID_B"
  ],
  "voice_settings": {
    "stability": 0.5
  },
  "inputs": [
    {
      "text": "Hello, how may I help you today?",
      "voice_id": "YOUR_VOICE_ID_A",
      "new_turn": true
    }
  ]
}

context_id

类型：string

必填：是

功能：由客户端指定，用于区分同一连接中的不同合成 context

限制：必须为非空字符串

除仅包含 close_socket 的消息外，每条消息都必须带 context_id。

voices

类型：string[]

必填：是，仅在 context 第一条消息中传入

数量：1 至 10 个

功能：注册当前 context 可以使用的 MyVocal 音色 ID

后续 inputs[].voice_id 必须是这里已经注册的音色。

voice_settings

类型：object

必填：否

位置：仅允许在 context 第一条消息中传入

当前 Context 声音设置使用下方列出的 stability；不要照搬 HTTP 的 similarity_boost、style 或 speed。

voice_settings.stability

类型：number

必填：否

范围：0 至 1

功能：控制生成稳定程度

数值越低，表达变化通常越丰富；数值越高，表现通常越稳定。

5. 持续发送文本

创建 context 后，可以多次发送 inputs：

{
  "context_id": "scene-001",
  "inputs": [
    {
      "text": "Sure, I can check that for you.",
      "voice_id": "YOUR_VOICE_ID_A"
    }
  ]
}

inputs

类型：object[]

必填：否

功能：向当前 context 追加一段或多段文本

inputs[].text

类型：string

必填：是

功能：需要合成的文本

建议按自然短句或句子持续发送，保留正常标点，以获得更自然的上下文和更快
的流式输出。

inputs[].voice_id

类型：string

必填：是

功能：指定本段文本使用的音色

限制：必须已在当前 context 的 voices 中注册

inputs[].new_turn

类型：boolean

必填：否

默认值：false

功能：设为 true 时结束当前语气段，并开始新的说话 turn

切换 voice_id 也会开始新的 turn。

6. 控制消息

立即处理缓冲文本

{
  "context_id": "scene-001",
  "flush": true
}

flush 强制处理当前 context 的缓冲文本，但不会关闭 context。完成后仍可
继续发送 inputs。

保持 Context 活跃

{
  "context_id": "scene-001",
  "keep_alive": true
}

keep_alive 重置当前 context 的 20 秒空闲计时，不会生成音频。

关闭单个 Context

{
  "context_id": "scene-001",
  "close_context": true
}

close_context 会自动处理剩余文本，发送该 context 的 is_final，然后
关闭该 context。其他 context 不受影响。

发送 close_context 前不需要额外发送 flush。

关闭整个连接

{
  "close_socket": true
}

close_socket 会处理并关闭全部 context。每个活跃 context 完成后，服务端
以 Close Code 1000 正常关闭 WebSocket。

7. 服务端消息

音频分片

{
  "audio": "<BASE64_AUDIO>",
  "context_id": "scene-001"
}

audio：Base64 编码音频分片

context_id：该音频所属的 context

客户端应按同一 context_id 内的到达顺序解码和拼接音频。

Turn 音频结束

{
  "context_id": "scene-001",
  "is_final_audio_for_turn": true
}

表示当前 turn 的音频已经发送完成，不代表 context 已关闭。

Context 结束

{
  "context_id": "scene-001",
  "is_final": true
}

表示该 context 的剩余音频已发送完成并已经关闭。

字符时间信息

当 timestamps=true 时，音频消息可能同时包含：

{
  "audio": "<BASE64_AUDIO>",
  "context_id": "scene-001",
  "alignment": {
    "chars": ["H", "e", "l", "l", "o"],
    "char_start_times_ms": [0, 80, 150, 220, 300],
    "char_durations_ms": [80, 70, 70, 80, 90]
  },
  "normalized_alignment": {
    "chars": ["H", "e", "l", "l", "o"],
    "char_start_times_ms": [0, 80, 150, 220, 300],
    "char_durations_ms": [80, 70, 70, 80, 90]
  }
}

alignment：原始文本的字符时间信息

normalized_alignment：规范化文本的字符时间信息

chars：字符序列

char_start_times_ms：字符起始时间，单位毫秒

char_durations_ms：字符持续时间，单位毫秒

8. 限制与生命周期

一个 WebSocket 连接最多同时保持 5 个活跃 context。

关闭 context 后会释放对应槽位。

每个 context 最多注册 10 个音色。

context 空闲超过 20 秒会自动处理剩余文本、发送 is_final 并关闭。

其他 context 不会因某个 context 空闲关闭而受影响。

voice_settings 只能在 context 第一条消息中设置。

协议或参数错误会返回 JSON 错误，并使用 Close Code 1008 关闭连接。

正常完成使用 Close Code 1000。

9. 错误响应

参数错误示例：

{
  "code": "INVALID_PARAMETER",
  "field": "voice_settings.stability",
  "message": "voice_settings.stability must be between 0 and 1"
}

并发线路错误示例：

{
  "error": "INVALID_PRIORITY",
  "message": "This WebSocket requires priority=dedicated_concurrency"
}

常见错误：

INVALID_PARAMETER：参数、消息结构或字段值无效

INVALID_PRIORITY：未使用 dedicated_concurrency

DEDICATED_CONCURRENCY_REQUIRED：当前账户没有可用独享并发

MAX_CONTEXT_LIMIT_EXCEEDED：同一连接超过 5 个活跃 context

INSUFFICIENT_QUOTA：账户可用额度不足

STREAMING_SERVICE_ERROR：语音生成服务暂时不可用

收到错误后，客户端应记录错误类型和 field，停止向当前连接继续发送
消息，并等待或处理服务端 Close Frame。

10. 用量

字符用量与字段说明请参阅查询主 Key 用量。

多角色对话 · 多 Context

最小交互流程#

模型选择#

1. 连接信息#

2. Query 参数#

priority#

model_id#

format#

language_code#

timestamps#

text_normalization#

seed#

enable_logging#

3. 消息流程#

4. 创建 Context#

context_id#

voices#

voice_settings#

voice_settings.stability#

5. 持续发送文本#

inputs#

inputs[].text#

inputs[].voice_id#

inputs[].new_turn#

6. 控制消息#

立即处理缓冲文本#

保持 Context 活跃#

关闭单个 Context#

关闭整个连接#

7. 服务端消息#

音频分片#

Turn 音频结束#

Context 结束#

字符时间信息#

8. 限制与生命周期#

9. 错误响应#

10. 用量#

请求参数

最小交互流程

模型选择

1. 连接信息

2. Query 参数

priority

model_id

format

language_code

timestamps

text_normalization

seed

enable_logging

3. 消息流程

4. 创建 Context

context_id

voices

voice_settings

voice_settings.stability

5. 持续发送文本

inputs

inputs[].text

inputs[].voice_id

inputs[].new_turn

6. 控制消息

立即处理缓冲文本

保持 Context 活跃

关闭单个 Context

关闭整个连接

7. 服务端消息

音频分片

Turn 音频结束

Context 结束

字符时间信息

8. 限制与生命周期

9. 错误响应

10. 用量