跳转到主要内容
Fun-ASR-Realtime

实时语音识别(Fun-ASR-Realtime)客户端事件

本文介绍 Fun-ASR-Realtime 实时语音识别服务中客户端通过 WebSocket 发送给服务端的客户端事件,包括 run-task(启动任务)、finish-task(结束任务)等指令的数据结构与字段含义。

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
        },
        "input": {}
    }
}
参数类型说明
headerobject(必选)
header.actionstring(必选) 指令类型,固定为 run-task。
header.task_idstring(必选) 客户端生成的任务 ID(UUID 格式),用于关联后续事件。
header.streamingstring(必选) 固定为 duplex。
payloadobject(必选)
payload.task_groupstring(必选) 任务组,固定为 audio。
payload.taskstring(必选) 任务类型,固定为 asr。
payload.functionstring(必选) 功能类型。固定为recognition。
payload.modelstring(必选) 模型名称。
payload.inputobject(必选) 输入对象。不携带上下文时传入{}。 提示: 仅 fun-asr-realtime 模型支持上下文。
payload.input.contextarray(object)(可选) 对话上下文,用于辅助识别、提升专有词汇的识别准确率。使用方法详见上下文增强。 提示: 上下文消息(input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度(user 和 assistant 的 text 字段长度之和)不超过 400 个字符(按字符数计算,每个字符计为 1),超出部分从末尾截断。 提示: 携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。
payload.input.context.rolestring(必选) 消息角色。取值范围:
  • user:前几轮用户语音的识别结果或领域相关的词表。
  • assistant:前几轮大语言模型的回复内容。
payload.input.context.contentarray(object)(必选) 消息内容列表。
payload.input.context.content.typestring(必选) 内容类型。取值范围:
  • input_text:前几轮用户语音的识别结果或领域相关的词表(role 为 user 时使用),需同时传入 text 字段。
  • text:前几轮大语言模型的回复内容(role 为 assistant 时使用),需同时传入 text 字段。
payload.input.context.content.textstring(必选) 文本内容。当 type 为 input_text 时,填入前几轮用户语音的识别结果或领域相关的词表;当 type 为 text 时,填入前几轮大语言模型的回复内容。
payload.parametersobject(必选) 语音识别参数。
payload.parameters.formatstring(必选) 音频格式。 取值范围:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
提示: opus/speex:必须使用Ogg封装; wav:必须为PCM编码; amr:仅支持AMR-NB类型。
payload.parameters.sample_rateinteger(必选) 采样率(Hz)。 取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。
payload.parameters.vocabulary_idstring(可选) 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。
payload.parameters.language_hintsarray[string](可选) 待识别音频语种。无默认值,不设置时模型自动识别。 仅支持设置 1 个值,设置多个时仅第一个生效。
  • fun-asr-realtime:
  • 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-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28:
  • zh: 中文
payload.parameters.max_sentence_silenceinteger(可选) VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:1300。 取值范围:[200, 6000]。
payload.parameters.multi_threshold_mode_enabledboolean(可选) 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。 默认值:false。
payload.parameters.heartbeatboolean(可选) 是否启用心跳包。 默认值:false。
  • true:在持续发送静音音频的情况下,可保持与服务端的连接不中断。
  • false(默认):即使持续发送静音音频,连接也将在一定时间后因超时而断开。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。
payload.parameters.speech_noise_thresholdfloat(可选) 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。 取值说明:
  • 取值越接近 -1:降低噪音判定阈值,噪音被识别为语音的概率增大,可能导致更多噪音被转写
  • 取值越接近 +1:提高噪音判定阈值,语音被误判为噪音的概率增大,可能导致部分语音被过滤
此参数为高级配置参数,调整可能显著影响识别效果,建议:
  • 调整前充分测试验证效果
  • 根据实际音频环境小幅度调整(建议步长 0.1)
payload.parameters.special_word_filterstring(可选) 敏感词过滤规则,用于将识别结果中的指定词汇替换为等长的星号,或从结果中移除。值为规则对象序列化后的 JSON 字符串。最多可设置 32 个敏感词;未传入该参数时不进行过滤。
  • 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\":false}"
}

finish-task

通知服务端音频发送完毕,请求结束任务。 发送时机:所有音频数据发送完毕后。 响应事件:服务端返回 task-finished 事件。
{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}
参数类型说明
headerobject(必选)
header.actionstring(必选) 指令类型,固定为 finish-task。
header.task_idstring(必选) 客户端生成的任务 ID(UUID 格式),需与run-task事件中的 task_id 保持一致。
header.streamingstring(必选) 固定为 duplex。
payloadobject(必选)
payload.inputobject(必选) 固定为{}。