实时多模态交互协议（WebSocket）

上传音频

上传音频时，将原始音频直接转为二进制流即可，无需额外处理。

上传的语音识别音频需满足：16bit（采样位深）、单声道、有符号、little-endian PCM编码，采样率参考Start消息的参数parameters.upstream.sample_rate的取值说明。

如果希望减少网络流量和带宽占用，用户可以把pcm音频编码为opus格式，同时设置上传音频格式为raw-opus或opus（区别详见参数说明）。

上传音频时，根据Start消息中upstream.mode设值不同，采取的措施也不同：

• mode为 tap2talk 或 duplex：客户端需持续上传音频，服务端自动检测语音活动。建议每100ms上传一次数据，间隔太长或太短会对延时和处理效率造成不利影响。

  • 音频上传速率计算公式：数据每次上传的字节数 = 采样率 * 采样位深/8 * 时间间隔（ms）

• mode为 push2talk：客户端无需持续上传音频，但需通过SendSpeech和StopSpeech通知服务端音频识别的开始和结束。发送SendSpeech后需立即上传音频，否则会增加处理时间。

下发音频

服务端将大模型回复发送至TTS生成语音然后下发给客户端：

• 下发音频为16bit单声道，采样率和编码由Start消息参数定义。

• 下发速度取决于TTS服务性能，通常快于播放速度。

• 音频下发前发送RespondingStarted事件；结束后发送RespondingEnded事件。

• 客户端需在播放完成后需上报LocalRespondingEnded，通知服务端播放结束。

Start - Input Message

请求开始会话消息。服务收到Start消息后，向客户端发送Started消息。

parameters.upstream的参数说明如下：

parameters.downstream的参数说明如下：

parameters.client_info的参数说明如下：

parameters.biz_params的参数说明如下：

客户端使用的三种模式对比：

示例如下：

{
    "header": {
        "action":"run-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "task_group":"aigc",
        "task":"multimodal-generation",
        "function":"generation",
        "model":"multimodal-dialog",
        "input":{
          "directive": "Start",
          "workspace_id": "llm-***********",
          "app_id": "****************"
        },
        "parameters":{
          "upstream":{
            "type": "AudioOnly",
            "mode": "duplex"
          },
          "downstream":{
            "voice": "longxiaochun_v2",
            "sample_rate": 24000
          },
          "client_info":{
            "user_id": "bin********207",
            "device":{
              "uuid": "432k*********k449"
            },
            "network":{
              "ip": "10.0.0.9"
            },
            "location":{
              "city_name": "北京市"
            }
          },
          "biz_params":{
            "user_defined_params": {
                "agent_id_xxxxx": {
                    "name": "value"
                }
            },
            "user_prompt_params": {
                "name": "value"
            },
            "user_query_params": {
                "name": "value"
            }
          }
        }
    }
}

Started - Output Message

示例如下：

Started返回消息样例

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "Started",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

Stop - Input Message

示例如下：

Stop请求样例

{
    "header": {
        "action":"finish-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "Stop",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

Stopped - Output Message

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "Stopped",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

DialogStateChanged - Output Message

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "DialogStateChanged",
          "state": "Listening",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

RequestToSpeak - Input Message

当前状态不是Listening，而用户又想说话时，先提交此事件，等待服务端应答。

具体触发此事件的用户行为根据交互类型有所不同，比如用户按下按钮、语音打断（依赖双工模块）等。

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "RequestToSpeak",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

RequestAccepted - Output Message 请求被准许

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "RequestAccepted",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

SendSpeech - Input Message

当Start消息指定模式为puhs2talk，在Listening状态时，通知服务端开始上传语音，语音数据应紧接着此事件之后发送。

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "SendSpeech",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

StopSpeech - Input Message

当Start消息指定模式为puhs2talk的时候，用户必须使用StopSpeech结束语音指令输入。

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "StopSpeech",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

SpeechStarted - Output Message

当服务端检测到asr语音起点时下发此事件。

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "SpeechStarted",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

SpeechEnded - Output Message

当服务端检测到asr语音尾点时下发此事件，如果客户端还在上传音频，则收到此事件后应停止上传音频。

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "SpeechEnded",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

RequestToRespond - Input Message

在Listening状态时，通知服务端与用户主动交互，服务端会根据type字段把在text字段中上传的文本直接转换为语音下发，或调用大模型，返回的结果再转换为语音下发。

parameters.biz_params的参数说明如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "RequestToRespond",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb",
          "type": "prompt",
          "text": "你好，你有什么想聊的呢"
        },
        "parameters":{
          "images":[{
              "type": "base64",
              "value": "base64String"
          }],
          "biz_params":{
            "user_defined_params":{},
            "videos": [
                  {
                    "action": "connect", 
                    "type": "voicechat_video_channel"
                  },
                  {
                    "action": "exit", 
                    "type": "voicechat_video_channel"
                  }
                ]
          }
        }
    }
}

RespondingStarted - Output Message

AI语音应答开始，sdk要准备接收服务端下发的语音数据

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "RespondingStarted",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

RespondingEnded - Output Message

AI语音应答结束

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "RespondingEnded",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

LocalRespondingStarted - Input Message

客户端开始播放服务端下发的音频

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "LocalRespondingStarted",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

LocalRespondingEnded - Input Message

客户端播放服务端下发的音频结束

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "LocalRespondingEnded",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

SpeechContent - Output Message

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    }},
    "payload": {
        "output":{
          "event": "SpeechContent",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb",
          "text": "一二三",
          "finished": false
        }
    }
}

RespondingContent - Output Message

示例如下：

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "RespondingContent",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb",
          "text": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务，请告诉我更多的细节，我会尽力帮助您。",
          "spoken": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务，请告诉我更多的细节，我会尽力帮助您。",
          "finished": true,
        "extra_info": {
          "commands": "[{\"name\":\"VOLUME_SET\",\"params\":[{\"name\":\"series\",\"normValue\":\"70\",\"value\":\"70\"}]}]",
          "tool_calls": [{
            "id": "",
            "type": "function",
            "function": {
              "name": "function_name",
              "arguments": "{\"id\": \"123\", \"name\": \"test\"}",
              "outputs": "函数调用结果",
              "status": {
                "code": 200,
                "message": "Success."
              }
            }
          }]
        }
        }
    }
}

UpdateInfo - Input Message

示例如下：

{
    "header": {
        "action":"continue-task",
        "task_id": "9B32878********************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "input":{
          "directive": "UpdateInfo",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        },
        "parameters":{
          "images":[{
              "type": "base64",
              "value": "base64String"
          }],
          "client_info": {
              "status": {
                  "bluetooth_announcement": {
                      "status": "stopped"
                  },
                  "stream_media_playback": {
                      "status": "stopped"
                  },
                  "phone_ringing": {
                      "status": "stopped"
                  },
                  "stream_media_playback_qq": {
                      "status": "stopped"
                  }
              }
          },
          "biz_params":{
          }
        }
    }
}

HeartBeat - Input Message

示例：

{
  "header": {
    "action": "continue-task",
    "task_id": "9B32878********************3D053",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "directive": "HeartBeat",
      "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
    }
  }
}

HeartBeat - Output Message

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "HeartBeat",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb"
        }
    }
}

Error - Output Message

{
    "header": {
        "event":"result-generated",
        "task_id": "9B32878********************3D053"
    },
    "payload": {
        "output":{
          "event": "Error",
          "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb",
          "error_code": 500,
          "error_name": "InternalLLMError", 
          "error_message": "Internal LLM error""
        }
    }
}