普通 TTS · 多 Context - MyVocal AI语音大模型API文档

同一连接管理多个独立语音任务，通过 context_id 区分。

支持模型：multilingual_v2、flash_v2_5。

模型支持范围

使用 V3、V4 或 V3 Turbo 时，请进入多角色对话接口。本页普通 TTS 协议不支持这些模型。

最小交互流程

建立连接 → 初始化 Context → 发送文本 → flush → close_context → 等待 Context final

接口地址

自动选择

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

美国

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

爱尔兰

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

日本

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

在路径中替换 {voice_id}，并在 WebSocket 握手 Header 中传入：

api-key: <YOUR_API_KEY>

API Key 只能放在 Header 中，不要放入 URL、日志或客户端公开代码。

握手参数

model_id

类型：string；必填：是；约束与说明：仅支持 flash_v2_5、multilingual_v2；不支持 myvocal_v3

priority

类型：string；必填：是；约束与说明：固定为 dedicated_concurrency

format

类型：string；必填：否；约束与说明：输出音频格式；默认 pcm_16000，可选值见下方参数表

idleTimeout

类型：integer；必填：否；约束与说明：Context 空闲超时秒数，默认 20，范围 1..180

language_code

类型：string；必填：否；约束与说明：2 到 3 位小写语言代码，例如 en、zh；必须与所选模型实际支持的语言一致

Timestamps

类型：boolean；必填：否；约束与说明：请求时间戳/对齐信息

directStreaming

类型：boolean；必填：否；约束与说明：请求直接流式音频；客户端仍须兼容 JSON Base64 音频和二进制帧

seed

类型：integer；必填：否；约束与说明：范围 0..4294967295；相同配置下用于提升生成一致性，不保证音频逐字节相同

auto_mode

类型：boolean；必填：否；约束与说明：自动实时生成模式

连接参数名为 format。若 SDK 中的对应选项名为 output_format，请通过该选项设置音频格式，避免重复设置不同值。

示例：

wss://api.voicelibrary.co/enterprise/v1/tts/{voice_id}/websocket/multi?model_id=flash_v2_5&priority=dedicated_concurrency&format=pcm_16000&idleTimeout=20&language_code=zh

language_code 支持语言

按模型查看普通 TTS WSS 语言清单。

Context 规则

context_id 必填且不能为空。

每个 Context 的第一条消息用于初始化。

voice_settings、previous_text、next_text、generation_config 属于初始化消息。

voice_settings 只应出现在该 Context 的第一条消息中。

一个连接最多同时存在 5 个 Context。

正常完成顺序必须是：发送文本 -> flush -> close_context -> 等待该 Context 的 final。

close_context 不是隐式 flush。未先 flush 就关闭表示打断或取消，不能保证输出剩余缓冲音频。

客户端消息

1. 初始化 Context

{
  "context_id": "ctx_001",
  "text": " ",
  "previous_text": "上一句，可选",
  "next_text": "下一句，可选",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.3,
    "use_speaker_boost": true
  },
  "generation_config": {
    "synthesisSchedule": [120, 160, 250, 290]
  }
}

stability、similarity_boost、style 的取值范围均为 0..1。

2. 发送文本

{
  "context_id": "ctx_001",
  "text": "Hello world.",
  "flush": false
}

3. Flush Context

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

4. 正常关闭 Context

先完成 flush，再发送：

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

随后等待该 Context 的 is_final=true 或 isFinal=true。

5. 打断或取消

需要立即打断时，可以直接发送 close_context=true。这会结束当前 Context；尚未 flush 的文本可能无法完整输出。

6. Context 保活

{
  "context_id": "ctx_001",
  "text": ""
}

7. 关闭整个 WebSocket

{
  "close_socket": true
}

服务端响应

JSON 音频分片：

{
  "context_id": "ctx_001",
  "audio": "BASE64_AUDIO_DATA",
  "is_final": false
}

Context 完成：

{
  "context_id": "ctx_001",
  "is_final": true
}

客户端应同时兼容 context_id / contextId 和 is_final / isFinal。

final 帧中的 audio 可以为空、缺失或为 null，仍表示该 Context 成功完成。

JSON 中的 audio 为 Base64；也可能收到二进制帧。只有在服务端协议能关联到 Context 时，才能把直接二进制音频路由给对应 Context。

时间戳/对齐数据可能位于 timestamps 或 alignment。

Context 级终止错误不应终止其他 Context；连接级错误会终止连接及所有活动 Context。

错误响应可包含 error 和 message。客户端应能处理未列出的错误码，并保留错误信息用于排查。

客户端不得在重连后自动重放已经提交的文本，以免重复播放。

正确调用顺序

connect -> initialize context -> send text -> flush -> close_context -> wait context final

关闭 WebSocket 前，应先让需要正常完成的 Context 到达 final；需要取消的 Context 可直接关闭。

普通 TTS · 多 Context

模型支持范围#

最小交互流程#

接口地址#

握手参数#

model_id#

priority#

format#

idleTimeout#

language_code#

Timestamps#

directStreaming#

seed#

auto_mode#

language_code 支持语言#

Context 规则#

客户端消息#

1. 初始化 Context#

2. 发送文本#

3. Flush Context#

4. 正常关闭 Context#

5. 打断或取消#

6. Context 保活#

7. 关闭整个 WebSocket#

服务端响应#

正确调用顺序#

请求参数