实时文字转语音 v3

Realtime TTS v3 是新接入推荐使用的 WebSocket 协议。Kitta AI、MiniMax 以及未来新增的实时引擎共用相同的 camelCase 事件、认证、计费和恢复流程。切换引擎只需修改 modelId，客户端无需编写供应商专用代码。

接口和能力发现

项目	值
WebSocket	`wss://kittaai.com/v3/tts/live`
子协议	`realtime.tts.msgpack.v3`
能力接口	实时服务域名上的 `GET /v3/tts/capabilities`

所有应用层消息均为 MessagePack 二进制帧，不是 JSON 文本帧。连接前先读取能力接口；它会返回当前启用的公共模型、控制项、格式、传输限制和模式，不会暴露物理路由。

认证

服务端客户端在 WebSocket 握手时发送 API Key：

Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v3

不要把凭证放入 URL。浏览器不能设置 Authorization 请求头，因此需要由可信后端调用 POST /v3/tts/browser-tickets 创建绑定 Origin 的一次性票据，再使用响应中的 WebSocket URL 和子协议。

浏览器使用响应中的 URL 和子协议建立连接，并将 { event: 'auth', token: 'rtv2_ticket_...' } 作为第一个 MessagePack 帧发送。

启动会话

{
  event: 'start',
  eventId: 'event-1',
  mode: 'simple',
  request: {
    voiceId: '00a1b221-6137-4b73-ad62-b0cbce134167',
    modelId: 'fishaudio-s21pro-flash',
    format: 'mp3',
    speed: 1,
    volume: 0,
    stability: 1,
    similarity: 1,
    language: 'zh',
    textNormalization: true,
    chunkLength: 200,
    latency: 'balanced'
  }
}

voiceId 和 modelId 必填，所选音色必须支持该公共模型。支持的产品控制项和格式以能力接口为准。未知或不支持的控制项会被忽略并返回结构化警告；ready.effectiveRequest 是实际生效请求的最终依据。

服务端随后返回 ready 事件，包含 protocolVersion、sessionId、requestId、modelId、voiceId、format、effectiveRequest 和可能存在的 warnings。

发送文本并接收音频

简单模式可以通过一个事件同时提交文本并触发生成：

{ event: 'input', eventId: 'event-2', text: '你好，世界。', commit: true }

需要显式分段时，先发送 commit: false 的 input，再发送 flush；可靠模式还支持带顺序号的 text 事件。使用 { event: 'stop' } 结束会话，使用 { event: 'ping', timestamp: Date.now() } 进行应用层心跳。

主要服务端事件包括 authenticated、ready、input_ack、segment_accepted、audio、usage、segment_completed、request_status、warning、error、finish 和 pong。audio.audio 为二进制数据。所有 v3 响应字段统一使用 camelCase。

可靠模式与恢复

可靠模式使用 mode: 'reliable' 并提供稳定的 requestId。重连后重复同一个标准化请求即可恢复或重放状态；不得用相同 ID 发送不同参数。

GET /v3/tts/requests/{requestId}
GET /v3/tts/requests/{requestId}/segments/{segmentId}/audio
Authorization: Bearer API_KEY

状态响应以 camelCase 返回 state、retryable、units、resultAvailable 和分段元数据。只有 resultAvailable 以及分段状态表明已保存结果时，才可下载恢复音频。

错误与兼容性

应处理结构化 error 中的 code、message、retryable、terminal 以及可选的 stage/path。升级 WebSocket 前也可能返回 HTTP 错误。仅当 retryable 为 true 时进行退避重试，并始终保留 requestId。

Realtime v2 的 /v2/tts/live 继续兼容，其 snake_case 事件和 realtime.tts.msgpack.v2 子协议保持不变。不要在同一个客户端混用 v2 与 v3 字段。迁移步骤见迁移指南。