音视频推流完整交互协议

4.2.1. 请求

POST /audio-realtime/session HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
X-Request-ID: req_start_001

{
  "specVersion": "1.0",
  "requestId": "req_start_001",
  "sessionId": "ses_001",
  "type": "SESSION_START",
  "occurredAt": "2026-08-06T10:00:00+08:00",
  "payload": {
    "entryContext": {
      "source": "VOICE_SKILL",
      "rawUtterance": "进入语音闲聊"
    },
    "rtc": {
      "provider": "ALIYUN_RTC",
      "channelId": "channel_001",
      "consumerUserId": "third_party_consumer_001",
      "consumerToken": "<RtcRoom.thirdToken>",
      "expiresAt": "2026-08-07T10:00:00+08:00"
    }
  }
}

payload.rtc 字段说明：

实现要求：

• 必须同时使用 channelId、consumerUserId 和 consumerToken 入会，不要从 token 推断 userId；

• RTC consumer 准备失败时，在提交 SSE 200 前返回错误；

• 同一 START 重试不得创建第二个 RTC consumer、第二条 SSE 或第二份业务会话。

4.2.2. 响应

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache

开发者服务应先完成 RTC consumer 的初始化和入会准备，再返回 SSE 200。平台确认 SSE 就绪后才会启动设备推流；过早返回 200 可能导致开头音频丢失。

4.2.3. 保活

SSE 空闲期间建议每 30 秒发送一次注释保活：

: keep-alive

平台默认连续 90 秒未收到完整的 SSE 帧时会关闭会话。保活帧和 output 帧都必须以空行结束。当前不支持 SSE 续连、Last-Event-ID 或消息重放；连接断开后应释放资源，由用户重新进入会话。

4.3.1. 播报Action：SPEAK

流向：开发者系统 -> 平台

{
  "type": "SPEAK",
  "payload": {
    "speechId": "speech_001",
    "index": 1,
    "hasNext": true,
    "text": "我先简单介绍一下，",
    "textDisplayMode": "APPEND_HIGHLIGHT"
  }
}

同一播报必须满足以下规则：

• 单片播报固定为 index=1, hasNext=false；

• 多个 speechId 不能交错发送；

• 同一 speechId 的 textDisplayMode 必须保持一致；

• 相同 speechId + index 的重复帧必须内容完全相同，平台只消费一次；

• hasNext=false 只表示该播报的文本输入结束，不表示音频已经播放完成；

• 已完成或已取消的 speechId 不能用于新的回复。

多片播报示例：

event: output
data: {"specVersion":"1.0","sessionId":"ses_001","actions":[{"type":"SPEAK","payload":{"speechId":"speech_001","index":1,"hasNext":true,"text":"李白是唐代诗人，","textDisplayMode":"APPEND_HIGHLIGHT"}}],"final":false}

event: output
data: {"specVersion":"1.0","sessionId":"ses_001","actions":[{"type":"SPEAK","payload":{"speechId":"speech_001","index":2,"hasNext":false,"text":"以浪漫奔放的诗风闻名。","textDisplayMode":"APPEND_HIGHLIGHT"}}],"final":false}

使用 APPEND_HIGHLIGHT 时，同一份 text 会在支持该能力的设备上随播报追加并高亮；不支持展示的设备仍会正常播报。NONE 或缺省表示只播报。开发者不需要判断设备是否有屏。

4.3.2. 停止当前播报Action：STOP_OUTPUT

流向：开发者系统 -> 平台

{
  "type": "STOP_OUTPUT",
  "payload": {
    "scope": "SPEAK",
    "reason": "BARGE_IN"
  }
}

• scope 必填，当前固定为 SPEAK；

• reason 可选，仅用于说明停止原因；

• 没有活跃播报时，STOP 按幂等空操作处理；

• STOP 后的新回复必须使用新的 speechId，并从 index=1 开始。

需要用新回复打断旧播报时，将 STOP 和新回复首片放在同一个 output 中，并保证 STOP 在前：

event: output
data: {"specVersion":"1.0","sessionId":"ses_001","actions":[{"type":"STOP_OUTPUT","payload":{"scope":"SPEAK","reason":"BARGE_IN"}},{"type":"SPEAK","payload":{"speechId":"speech_002","index":1,"hasNext":false,"text":"三加三等于六。"}}],"final":false}

不要在同一回复的每个分片前重复发送 STOP。新播报开始后才到达的 STOP 也会停止新播报，因此必须由单 writer 保证顺序，并丢弃被新一轮对话替换的旧任务结果。