跳转到主要内容
千问 AI 平台 home page
文档
实时

实时语音识别（Fun-ASR）客户端事件

Fun-ASR 实时语音识别 WebSocket 客户端事件参考

客户端事件是客户端通过 WebSocket 发送给 Fun-ASR 实时语音识别服务的 JSON 指令：run-task 启动识别任务、continue-task 更新上下文、finish-task 结束任务。 用户指南：模型详情和选型建议请参见语音识别模型。 交互流程：事件交互时序图请参见 WebSocket API。服务端事件请参见服务端事件。

run-task

建立连接后，发送此指令启动识别任务并设置参数。 发送时机：WebSocket 连接建立后立即发送。 响应：服务端返回 task-started 事件后，客户端方可开始发送音频。 示例：
  • 基本请求
  • 携带上下文
{
  "header": {
    "action": "run-task",
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "streaming": "duplex"
  },
  "payload": {
    "task_group": "audio",
    "task": "asr",
    "function": "recognition",
    "model": "fun-asr-realtime",
    "parameters": {
      "format": "pcm",
      "sample_rate": 16000,
      "vocabulary_id": "vocab-xxx-24ee19fa8cfb4d52902170a0xxxxxxxx"
    },
    "input": {}
  }
}
header 参数：
参数类型是否必选说明
header.actionstring是指令类型。设为 run-task。
header.task_idstring是唯一任务 ID。在 finish-task 指令中须使用相同值。
header.streamingstring是通信模式。设为 duplex。
payload 参数：
参数类型是否必选说明
payload.task_groupstring是任务组。设为 audio。
payload.taskstring是任务类型。设为 asr。
payload.functionstring是功能类型。设为 recognition。
payload.modelstring是支持的模型名称。
payload.inputobject是输入对象。不携带上下文时传入 {}。详见下方 context 参数。
payload.parameters
formatstring是音频格式：pcm、wav、mp3、opus、speex、aac、amr。详见 WebSocket API 音频要求。
sample_rateinteger是音频采样率，单位 Hz。8k 模型仅支持 8000 Hz，其他模型支持任意采样率。
vocabulary_idstring否热词表 ID，用于热词识别。详见自定义热词。
semantic_punctuation_enabledboolean否是否启用语义标点。默认值：false。
- true：高精度标点，适用于会议场景。启用后将禁用 VAD 标点。
- false：低延迟 VAD 标点，适用于交互场景。
语义标点在断句准确性上更优，VAD 标点响应更快。
max_sentence_silenceinteger否VAD 静音阈值，单位毫秒。静音时长超过此值时断句。默认值：1300。取值范围：[200, 6000]。仅在 semantic_punctuation_enabled 为 false 时生效。
multi_threshold_mode_enabledboolean否防止 VAD 模式下产生过长语句。默认值：false。仅在 semantic_punctuation_enabled 为 false 时生效。
heartbeatboolean否是否启用保活。默认值：false。
- true：持续发送静音音频时保持连接不断开。
- false：连续 60 秒发送静音音频后连接超时断开。
language_hintsarray[string]否识别语言代码。不设置时自动检测语言。系统仅读取数组中的首个值，多余值将被忽略。不同模型支持的语言代码如下：
fun-asr-realtime、fun-asr-realtime-2025-11-07：zh（中文）、en（英文）、ja（日语）、ko（韩语）、vi（越南语）、th（泰语）、id（印尼语）、ms（马来语）、tl（菲律宾语）、hi（印地语）、ar（阿拉伯语）、fr（法语）、de（德语）、es（西班牙语）、pt（葡萄牙语）、ru（俄语）、it（意大利语）、nl（荷兰语）、sv（瑞典语）、da（丹麦语）、fi（芬兰语）、no（挪威语）、el（希腊语）、pl（波兰语）、cs（捷克语）、hu（匈牙利语）、ro（罗马尼亚语）、bg（保加利亚语）、hr（克罗地亚语）、sk（斯洛伐克语）
fun-asr-realtime-2026-02-28：zh（中文）、en（英文）、ja（日语）
fun-asr-realtime-2025-09-15：zh（中文）、en（英文）
fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28：zh（中文）
speech_noise_thresholdfloat否语音噪声检测阈值，用于调节 VAD 灵敏度。取值范围：[-1.0, 1.0]。接近 -1：更多噪声可能被识别为语音。接近 +1：部分语音可能被过滤为噪声。
special_word_filterstring否敏感词过滤配置，仅 Fun-ASR 支持。最多支持设置 32 个敏感词。参见敏感词过滤。
speech_noise_threshold 是高级参数，微小的调整会显著影响识别质量。建议以 0.1 为步长逐步调整，并充分测试。

敏感词过滤

敏感词过滤可对识别结果中的敏感词执行替换或移除，适用于客服质检、内容合规、字幕审核等场景。仅 Fun-ASR 支持，最多支持设置 32 个敏感词。未传入 special_word_filter 参数时，不会对敏感词进行过滤。 special_word_filter 为 JSON 对象，包含三个子字段：
  • filter_with_signed.word_list：字符串数组，列出需要被替换为等长 * 的敏感词。例如 ["测试"]，"帮我测试一下"会变成"帮我**一下"。
  • filter_with_empty.word_list：字符串数组，列出需要从结果中完全移除的敏感词。例如 ["开始"]，"比赛这就要开始了吗"会变成"比赛这就要了吗"。
  • system_reserved_filter：布尔值，默认 false。是否启用敏感词过滤功能。
配置示例： 
{
  "special_word_filter": {
    "filter_with_signed": {
      "word_list": ["测试"]
    },
    "filter_with_empty": {
      "word_list": ["开始", "发生"]
    },
    "system_reserved_filter": true
  }
}

context 参数

payload.input.context 字段用于传入对话上下文，辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。
仅 fun-asr-realtime 和 fun-asr-realtime-2025-11-07 模型支持 context 参数。
参数类型是否必选说明
contextarray[object]否对话上下文数组。
context[].rolestring是消息角色。user：前几轮用户语音的识别结果或领域相关的词表；assistant：前几轮大语言模型的回复内容。
context[].contentarray[object]是消息内容列表。
context[].content[].typestring是内容类型。input_text：用户语音识别结果或词表（role 为 user 时）；text：模型回复内容（role 为 assistant 时）。
context[].content[].textstring是文本内容。
  • 上下文消息（input_text 和 text 类型）各最多 5 条，超出时保留最近的 5 条。
  • 每轮上下文文本总长度（user 和 assistant 的 text 字段长度之和）不超过 400 个字符，超出部分从末尾截断。
  • 上下文消息必须按对话轮次排列，每轮中 user（input_text 类型）必须在对应的 assistant（text 类型）之前。

continue-task

在任务执行过程中更新对话上下文信息，用于辅助识别。 发送时机：任务运行中，需要更新对话上下文时发送。
仅 fun-asr-realtime 和 fun-asr-realtime-2025-11-07 模型支持该事件。
示例： 
{
  "header": {
    "action": "continue-task",
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "context": [
        {
          "role": "user",
          "content": [
            {
              "type": "input_text",
              "text": "你好啊"
            }
          ]
        },
        {
          "role": "assistant",
          "content": [
            {
              "type": "text",
              "text": "你好啊，我是通义千问，有什么可以帮助你的？"
            }
          ]
        }
      ]
    }
  }
}
header 参数：
参数类型是否必选说明
header.actionstring是指令类型。设为 continue-task。
header.task_idstring是任务 ID。须与 run-task 指令中的 task_id 一致。
header.streamingstring是通信模式。设为 duplex。
payload 参数：
参数类型是否必选说明
payload.inputobject是输入对象。
payload.input.contextarray[object]否对话上下文。参数结构同 context 参数。

finish-task

通知服务器音频传输已完成。 发送时机：所有音频数据发送完毕后。 响应：服务端返回 task-finished 事件。 示例： 
{
  "header": {
    "action": "finish-task",
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
header 参数：
参数类型是否必选说明
header.actionstring是指令类型。设为 finish-task。
header.task_idstring是任务 ID。须与 run-task 指令中的 task_id 一致。
header.streamingstring是通信模式。设为 duplex。
payload 参数：
参数类型是否必选说明
payload.inputobject是输入配置。设为 {}。