实时音视频 WebSocket 接入（新）

接口描述
本接口服务采用 WebSocket 协议，对实时音频流进行识别，同步返回识别结果，达到“边说边出文字”的效果。
说明：
2026 年 9 月 24 日起新用户请使用本文档接入 v3 新版接口。
已接入旧版 WebSocket v2 协议接口的用户可跳转 WebSocket 接入（旧） 查看相关说明文档。
前提条件
需要准备两个凭证：SDKAppID 与 SecretKey。
参数
获取位置
说明
SDKAppID
﻿TRTC 控制台 > 应用管理
TRTC 应用 ID，v3 的唯一客户维度。
SecretKey
﻿TRTC 控制台 > 应用概览 > SDK 密钥
用于生成 UserSig，不会传输到网络。
接口要求
内容
说明
语言种类
支持中文普通话、中文方言、英语，以及日语、韩语、法语等其他语种。
支持行业
通用。
音频属性
采样率：16000Hz 或 8000Hz；采样精度：16bits；声道：单声道（mono）。
音频格式
1 pcm、4 speex、6 silk、8 mp3、10 opus（裸 Opus 帧流）、11 ogg（Ogg 封装，含 .opus/.ogg 文件）、12 wav、14 m4a、16 aac。
说明：
Opus 是编码格式，实际传输有两种封装，对应不同的 voice_format：
10（裸 Opus 帧流）：音频是连续的 Opus 帧序列，每帧前带2字节小端长度前缀。
11（Ogg 封装）：音频是 Ogg 容器文件，文件头前4字节为 OggS。常见的 .opus、.ogg 文件都属于此类（容器内部编码可为 Opus 或 Vorbis）。用现成音频文件推流时请选 11。
判断方法：查看文件前4字节，是 OggS 就填 11。
请求协议
WSS 协议。
请求地址
wss://asr.cloud-rtc.com/asr/v3?voice_id=<voice_id>
鉴权信息通过首帧消息的 auth 块传入，URL 上不携带鉴权参数。
响应格式
JSON。
数据发送
每 40ms 发送 40ms 时长（即 1:1 实时率）的数据包，对应 PCM 大小为：8k 采样率640字节，16k 采样率1280字节。单帧不超过256KB。建连后需在3秒内发送首帧；音频数据包之间发送间隔超过15秒，后台将返回错误并主动断开连接。
并发限制
默认单账号（SDKAppID）限制并发数为200路。
说明：
同一 SDKAppID 下，直接接入 ASR、AI 对话、AI 转录/翻译等所有实时语音识别场景共享该并发池，即各类型的并发路数合计不超过账号上限。一句话识别与录音文件识别独立计算，不占用实时识别并发额度。如您有更多并发需求，请 联系我们。
业务流程图
﻿
﻿
﻿
对应的 SDK 行为：Start() 完成 ①②（同步等待 ack，鉴权或参数错误立即返回 error）；Write() 对应 ③ 上行；下行经 listener 回调 OnSentenceBegin / OnRecognitionResultChange / OnSentenceEnd / OnRecognitionComplete；Stop() 发送 end 并等待 final:1。
接口调用流程
接口调用流程分为三个阶段：建立连接、鉴权、识别。鉴权与识别阶段后台均返回 text message，内容为 JSON 序列化字符串，以下是公共字段格式说明：
字段名
类型
描述
code
Integer
状态码，0 代表正常，非 0 值表示发生错误。
message
String
错误说明。
voice_id
String
音频流全局唯一标识，一个 WebSocket 连接对应一个，用户自己生成（推荐使用 UUID），最长128位。
message_id
String
本 message 唯一 ID。
result
Result
最新语音识别结果，结构见 识别结果。
final
Integer
该字段返回1时表示音频流全部识别结束。
建连阶段
客户端发起 WebSocket 连接请求，请求 URL 格式为：wss://asr.cloud-rtc.com/asr/v3?voice_id=<voice_id>。
URL 上只携带 voice_id，不携带任何鉴权参数。voice_id 同时出现在 URL ?voice_id= 与首帧 params.voice_id 中，两者需一致，或在 params 中省略。SDK 默认生成 uuid，可通过 SetVoiceID 指定。
鉴权阶段
连接建立后，客户端需在 3秒内 发送首帧 text message，内容为 JSON，同时完成鉴权与参数下发：
{
  "type": "start",
  "auth": {"sdkappid": "1400000001", "usersig": "eJw..."},
  "params": {"engine_model_type": "bigmodel", "language": "zh", "voice_format": 1, "needvad": 1}
}
type 固定为 start。首帧 JSON 非法或 type 非 start 时，服务端返回 4010；超过3秒未发送首帧，返回 4008。
鉴权通过后服务端返回 code 值为0的确认消息表示鉴权成功：
{"code": 0, "message": "success", "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd"}
鉴权或参数校验失败时，服务端返回 code 为非0值的错误帧（如 4002 鉴权失败、4001 参数不合法），随后正常关闭连接。
SDK 的 Start() 会同步等待该 ack，鉴权与参数错误直接从 Start() 返回。
auth 字段说明
一条 WebSocket 连接即一条流，voice_id 既是流身份、也是签名 identifier，因此 auth 块中不再重复携带。
字段
类型
必填
说明
sdkappid
String
是
TRTC 应用 ID，取自 credential，SDK 自动填写。
usersig
String
是
TRTC 签名，identifier = 当前 voice_id，SDK 按该值签发。计算方式请参见 用户鉴权。
说明：
在线协议没有 request_id。request_id 是离线接口 “一次请求 = 一个事务” 的概念，流式协议里不存在。
签名规则
1. 未调用 credential.SetUserSig() 时，SDK 使用 SDKAppID + SecretKey 本地生成签名，有效期 86400 秒，且每条连接都重新生成，长跑服务无需自行管理过期。
2. 调用 credential.SetUserSig(sig) 传入固定签名后，SDK 不再生成也不再刷新。服务端使用当前 identifier（在线为 voice_id）验签，因此签名必须用同一个 identifier 签发。固定签名场景（如浏览器端由业务后端下发签名）需自行处理过期与 identifier 对齐。
3. 签名与站点绑定。SetSite(common.SiteIntl) 决定 host 与验签集群，国际站凭证不可用于国内站，反之亦然。
4. SecretKey 不会传输到网络，签名只用于服务端验签。
params 参数说明
参数名
必填
类型
描述
voice_id
否
String
音频流全局唯一标识，一个 WebSocket 连接对应一个，用户自己生成（推荐使用 UUID），最长 128 位。需与 URL 参数一致，或省略。
engine_model_type
是
String
语音识别 2.0（推荐）
bigmodel：大模型引擎，支持实时说话人分离。
语音识别 1.0
基础版引擎：8k_zh。
标准版引擎：可配置 8k_zh_large、16k_zh_large 或 16k_zh_en。
高级版引擎：小语种 ASR 引擎，传参是“16k_具体语种 code”，例如 16k_vi（越南语）。
language
否
String
语音识别 2.0（推荐）
bigmodel 支持 zh（中文普通话、中文方言和中英混）、en（英语）、yue（粤语）和小语种。
中文方言：安徽、东北、福建、甘肃、贵州、河北、河南、湖北、湖南、江西、宁夏、山东、陕西、山西、四川、天津、云南、浙江、粤语（香港口音）、粤语（广东口音）、吴语、闽南语。
小语种：ar（阿拉伯语）、de（德语）、fr（法语）、es（西班牙语）、pt（葡萄牙语）、id（印尼语）、it（意大利语）、ko（韩语）、ru（俄语）、th（泰语）、vi（越南语）、ja（日语）、tr（土耳其语）、hi（印地语）、ms（马来语）、nl（荷兰语）、sv（瑞典语）、da（丹麦语）、fi（芬兰语）、pl（波兰语）、cs（捷克语）、fa（波斯语）、el（希腊语）、ro（罗马尼亚语）、hu（匈牙利语）、mk（马其顿语）。
语音识别 1.0
基础版：8k_zh 支持中文普通话和中文方言。
标准版：8k_zh_large、16k_zh_large 支持中文普通话和中文方言；16k_zh_en 支持中文普通话、中文方言、英语和中英混。
高级版：vi（越南语）、ja（日语）、ko（韩语）、id（印度尼西亚语）、th（泰语）、pt（葡萄牙语）、tr（土耳其语）、ar（阿拉伯语）、es（西班牙语）、hi（印地语）、fr（法语）、ms（马来语）、fil（菲律宾语）、de（德语）、it（意大利语）、ru（俄语）、sv（瑞典语）、da（丹麦语）、no（挪威语）。
如果您有更多语言需求，请 联系我们 评估。
说明：
当 engine_model_type 配置为 bigmodel，不填写 language 字段时，模型会自动识别语种；使用 SDK 时建议显式指定。
voice_format
否
Integer
语音编码方式，默认 1。取值：1 pcm、4 speex、6 silk、8 mp3、10 opus（裸 Opus 帧流）、11 ogg（Ogg 封装，含 .opus/.ogg 文件）、12 wav、14 m4a、16 aac。
说明：
Opus 是编码格式，实际传输有两种封装，对应不同取值。10 裸 Opus 帧流——音频是连续的 Opus 帧序列，每帧前带2字节小端长度前缀；11 Ogg 封装——音频是 Ogg 容器文件，文件头前4字节为 OggS，常见的 .opus、.ogg 文件都属于此类（容器内部编码可为 Opus 或 Vorbis），用现成音频文件推流时请选 11。
判断方法：查看文件前4字节，是 OggS 就填 11。
实时推流场景建议使用 pcm（16kHz、16bit、单声道）。
input_sample_rate
否
Integer
支持 PCM 格式的 8k 音频在与引擎采样率不匹配的情况下升采样到 16k 后识别，能有效提升识别准确率。仅支持：8000。
注意：
此参数仅适用于 PCM 格式音频，不传入值将维持默认状态，即默认调用的引擎采样率等于 PCM 音频采样率。
needvad
否
Integer
0 关闭 vad。
1 开启 vad。
不传时由引擎决定（Go SDK 默认下发 1）。为保证识别效果，如果语音分片长度超过 60 秒，会强制在 60s 断一次，建议音频超过 60s 时开启 vad（人声检测切分功能），提升切分效果。
vad_silence_time
否
Integer
语音断句检测阈值，静音时长超过该阈值会被认为断句（多用在智能客服场景，需配合 needvad=1 使用），取值范围 240-2000（默认 800），单位 ms。此参数建议不要随意调整，可能会影响识别效果。
vad_level
否
Integer
VAD 场景档：
0 高召回。
1 远场过滤。
默认 1。设置 noise_threshold 后覆盖本档位。
noise_threshold
否
Float
噪音参数阈值，取值范围 [0.0, 4.0]。对于一些音频片段，取值越大，判定为噪音情况越大；取值越小，判定为人声情况越大。不传时走服务端缺省。
max_speak_time
否
Integer
强制断句功能，取值范围 5000-90000（单位：毫秒），默认值 60000。在连续说话不间断情况下，该参数将实现强制断句（此时结果变成稳态，slice_type=2）。例如游戏解说场景，解说员持续不间断解说、无法断句的情况下，将此参数设置为 10000，则将在每10秒收到 slice_type=2 的回调。
filter_dirty
否
Integer
是否过滤脏词（目前支持中文普通话引擎）。默认为 0。
0 不过滤脏词。
1 过滤脏词。
2 将脏词替换为 *。
filter_modal
否
Integer
是否过滤语气词（目前支持中文普通话引擎）。默认为 0。
0 不过滤语气词。
1 部分过滤。
2 严格过滤。
filter_punc
否
Integer
是否过滤句末的句号（目前支持中文普通话引擎）。默认为 0。
0 不过滤句末的句号。
1 过滤句末的句号。
filter_empty_result
否
Integer
空结果是否下发：
0 下发。
1 不下发。
默认 1。
convert_num_mode
否
Integer
是否进行阿拉伯数字智能转换（目前支持中文普通话引擎）：
0 不转换，直接输出中文数字。
1 根据场景智能转换为阿拉伯数字。
3 数学模式。
默认值为 1。
word_info
否
Integer
是否显示词级别时间戳：
0 不显示。
1 显示，不包含标点时间戳。
2 显示，包含标点时间戳；100 字幕模式。
默认 0。
word_with_space
否
Integer
英文单词间是否输出空格。默认 0。
hotword_id
否
String
热词表 ID，SDKAppID 维度。需先在控制台创建热词表。
hotword_list
否
String
临时热词表：该参数用于提升识别准确率。单个热词限制：“热词|权重”，单个热词不超过30个字符（最多10个汉字），权重 [1-11] 或者100，例如 “腾讯云|5” 或 “ASR|11”；临时热词表限制：多个热词用英文逗号分割，最多支持128个热词，例如 “腾讯云|10,语音识别|5,ASR|11”。
注意：
热词权重设置为11时，当前热词将升级为超级热词，建议仅将重要且必须生效的热词设置到11，设置过多权重为11的热词将影响整体字准率。热词权重设置为100时，当前热词开启热词增强同音替换功能。
举例：热词配置“蜜制|100”时，与“蜜制”同拼音（mizhi）的“秘制”的识别结果会被强制替换成“蜜制”。因此建议客户根据自己的实际情况开启该功能。建议仅将重要且必须生效的热词设置到100，设置过多权重为100的热词将影响整体字准率。热词不能包含空格。
speaker_diarization
否
Integer
实时说话人分离配置项。
0 不开启说话人分离。
1 开启说话人分离（匿名聚类）。
3 开启说话人分离基础上增加角色认证，需配合 voiceprint_ids 或 speaker_roles 参数使用。
默认值：0。
注意：
取 1 或 3 时，服务端会强制开启 VAD 并调整 word_info。
speaker_number
否
Integer
说话人数量提示，0 表示自动检测。两种分离模式都生效。
voiceprint_ids
否
String Array
实时说话人声纹匹配 ID 配置项。该参数值通过声纹注册接口注册获取，参数为数组，最大可支持 32 个声纹。仅 speaker_diarization=3 时生效。示例：["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440002"]。
speaker_roles
否
Object Array
临时声纹，仅在本次识别中生效，仅 speaker_diarization=3 时生效。格式 [{"audio_url":"...","role_name":"..."}]。命中后 role_name 会回显到识别结果的 speaker_name。
context
否
Object
识别上下文：{"text":"背景文本","terms":["术语"],"general":[{"key":"domain","value":"Meeting"}]}。
识别阶段
上传数据
鉴权成功后，客户端持续上传 binary message 到后台，内容为音频流二进制数据。每 40ms 发送 40ms 时长（即 1:1 实时率）的数据包，对应 PCM 大小为：8k 采样率640字节，16k 采样率1280字节。单帧不超过256KB。音频数据包之间发送间隔超过15秒，后台将返回 4008 并主动断开连接。
音频流上传完成之后，客户端需发送以下内容的 text message，通知后台结束识别。
{"type": "end"}
接收消息
客户端上传数据的过程中，需要同步接收后台返回的实时识别结果，结果示例：
{
    "code": 0,
    "message": "success",
    "voice_id": "23c33398-4da0-4ba7-b0ec-7565b325301d",
    "message_id": "756d2992-5a23-488a-b391-9c9c0c36bedf",
    "result": {
        "slice_type": 0,
        "index": 0,
        "start_time": 0,
        "end_time": 6000,
        "voice_text_str": "欢迎来到 ASR。",
        "language": "zh",
        "word_size": 0,
        "word_list": []
    }
}
后台识别完所有上传的语音数据之后，最终返回 final 值为 1 的消息并断开连接。
{
    "code": 0,
    "message": "success",
    "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd",
    "message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8",
    "final": 1
}
识别过程中如果出现错误，后台返回 code 为非 0 值的消息并断开连接。
{
    "code": 4008,
    "message": "后台识别服务器音频分片等待超时",
    "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd",
    "message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8"
}
识别结果
字段名
类型
描述
slice_type
Integer
识别结果类型：
0 一段话开始识别。
1 一段话识别中，voice_text_str 为非稳态结果（该段识别结果可能变化）。
2 一段话识别结束，voice_text_str 为稳态结果（该段识别结果不再变化）。
根据发送的音频情况，识别过程中可能返回的 slice_type 序列有：
0-1-2（一段话开始识别、识别中可能有多次 1 返回、识别结束）。
0-2。
或直接返回 2（一段话完整的识别结果）。
index
Integer
当前一段话结果在整个音频流中的序号，从0开始逐句递增。
start_time
Integer
当前一段话结果在整个音频流中的起始时间。
end_time
Integer
当前一段话结果在整个音频流中的结束时间。
voice_text_str
String
当前一段话文本结果，编码为 UTF8。
language
String
当前一段话识别的语种类型，例如 zh。
word_size
Integer
当前一段话的词结果个数（word_list 数组的长度与 word_size 的值相等）。
word_list
Word Array
当前一段话的词列表，结构见下。需 word_info != 0。
speaker_segments
SpeakerSegment Array
当开启实时说话人分离时会有该结果返回，表示当前句子的说话人片段结果。
finish_silence_ms
Integer
触发断句的尾部静音时长（ms）。
last_token_runtime_ms
Integer
末字服务端解码耗时（ms）。
Word 结构体
字段名
类型
描述
word
String
该词的内容。
start_time
Integer
该词在整个音频流中的起始时间。
end_time
Integer
该词在整个音频流中的结束时间。
stable_flag
Integer
该词的稳态结果：
0 表示该词在后续识别中可能发生变化。
1 表示该词在后续识别过程中不会变化。
speaker_id
Integer
当开启实时说话人分离时会有该内容。
-1 未知说话人。
>0 说话人 ID。
speaker_name
String
已注册声纹说话人标识。
说话人分离
开启 speaker_diarization 后，说话人分离的标识结果通过两个入口返回：
result.speaker_segments[]（推荐入口）：一个 result 可能包含多个说话人，句子级归属天然有歧义，因此协议按说话人切段返回。len(speaker_segments) == 1 即为单说话人句。
result.word_list[].speaker_id：字级归属，需同时设置 word_info != 0。
speaker_id 语义：会话内有效，从 1 开始编号，-1 表示未知说话人，0 为保留值。
speaker_segments 字段
字段
类型
说明
speaker_id
Integer
说话人 ID。
-1 未知说话人。
>0 说话人 ID。
speaker_name
String
已注册声纹说话人标识。仅 speaker_diarization=3 且命中注册声纹时返回，等于请求侧的 role_name。
start_time
Integer
片段开始时间（ms）。
end_time
Integer
片段结束时间（ms）。
text
String
该分段文本。
word_start
Integer
对应 word_list 的开始位置下标（闭区间）。word_info=0 时不返回。
word_end
Integer
对应 word_list 的结束位置下标（闭区间），即 word_list[word_start:word_end+1]。word_info=0 时不返回。
stable_flag
Integer
是否稳态结果：
1 稳定。
0 非稳定。
VAD 调优
方法
取值
说明
SetVadLevel(level)
0 / 1
0 高召回。
1 远场过滤（服务端默认）。
SetNoiseThreshold(v)
0.0 - 4.0
噪声抑制微调，值越大抑制越强、召回越低。设置后覆盖 vad_level 档位。
SetVadSilenceTime(ms)
240 - 2000
静音断句阈值。
两者都是三态语义：只有显式调用 setter 才会下发，因此显式传 0 与「不配置」可以区分（服务端 vad_level 默认为 1）。取值超出范围会在 Start() 阶段本地报错，不会浪费一次连接。
开发者资源
安装
go get github.com/Tencent-RTC/trtc-asr-sdk-go@latest
要求 Go 1.21 及以上。
SDK
Tencent-RTC SDK for Go：Github﻿
Tencent-RTC SDK for Python：Github﻿
Tencent-RTC SDK for nodejs：Github﻿
Tencent-RTC SDK for Java：Github﻿
Tencent-RTC SDK for Rust：Github﻿
Tencent-RTC SDK for cpp：Github﻿
SDK 调用示例
单击查看 Golang 示例。
初始化凭证
import (
    v3 "github.com/Tencent-RTC/trtc-asr-sdk-go/asr/v3"
    "github.com/Tencent-RTC/trtc-asr-sdk-go/common"
)
﻿
// 第一个参数是 SDKAppID（如 1400xxxxxx）；v3 不需要腾讯云 AppID。
credential := v3.NewCredential(sdkAppID, "your-sdk-secret-key")
// credential.SetSite(common.SiteIntl) // 国际站；不调用则走国内站
发起实时识别
type MyListener struct{ v3.UnimplementedSpeechRecognitionListener }
﻿
func (l *MyListener) OnSentenceEnd(resp *v3.SpeechRecognitionResponse) {
    log.Printf("Sentence end: %s", resp.Result.VoiceTextStr)
}
func (l *MyListener) OnFail(resp *v3.SpeechRecognitionResponse, err error) {
    log.Printf("Failed: %v", err) // err 为 *common.ASRError，Code 即服务端错误码
}
﻿
recognizer := v3.NewSpeechRecognizer(credential, "bigmodel", &MyListener{})
recognizer.SetLanguage("zh") // bigmodel 建议显式指定语种
if err := recognizer.Start(); err != nil {
    log.Fatal(err) // 鉴权失败/参数非法在这里同步返回
}
// recognizer.Write(pcmChunk) ... 循环发送音频
recognizer.Stop() // 发送 {"type":"end"} 并等待 final
开启说话人分离
recognizer := v3.NewSpeechRecognizer(credential, "bigmodel", &MyListener{})
recognizer.SetLanguage("zh")
recognizer.SetWordInfo(1)                                      // 需要字级说话人时开启
recognizer.SetSpeakerDiarization(v3.SpeakerDiarizationCluster)  // 1：匿名聚类
﻿
// 声纹角色认证（返回角色名）：
// recognizer.SetSpeakerDiarization(v3.SpeakerDiarizationVoiceprint) // 3
// recognizer.SetSpeakerRoles([]v3.SpeakerRole{
//     {RoleName: "teacher", AudioURL: "https://example.com/teacher.wav"},
// })
// recognizer.SetVoiceprintIDs([]string{"vp-1"}) // 已注册声纹
// recognizer.SetSpeakerNumber(2)                // 0 = 自动检测
﻿
// 回调中读取分段结果：
func (l *MyListener) OnSentenceEnd(resp *v3.SpeechRecognitionResponse) {
    for _, seg := range resp.Result.SpeakerSegments {
        name := seg.SpeakerName            // speaker_diarization=3 才有
        if name == "" {
            name = fmt.Sprintf("spk%d", seg.SpeakerID)
        }
        log.Printf("[%s] %s", name, seg.Text)
    }
}
运行示例
cd examples/v3_realtime_asr
go run main.go -e bigmodel -f ../test.pcm
﻿
# 说话人分离（匿名聚类 + 字级说话人）
go run main.go -e bigmodel -f ../test.pcm -diarization 1 -word-info 1
﻿
# 说话人分离（声纹角色认证，返回角色名）
go run main.go -e bigmodel -f ../test.pcm -diarization 3 \\
  -roles "teacher=https://example.com/teacher.wav,student=https://example.com/student.wav"
﻿
# 查看所有选项
go run main.go -h
配置项
方法
说明
默认值
SetVoiceFormat(f)
音频格式。
1（PCM）
SetNeedVad(v)
是否开启 VAD（显式 0 会真正下发关闭）。
1（开启）
SetConvertNumMode(m)
数字转换：0 不转 / 1 智能 / 3 数学（显式 0 生效）。
1（智能）
SetHotwordID(id)
热词表 ID（SDKAppID 维度）。
-
SetHotwordList(list)
临时热词列表 词|权重,...。
-
SetFilterDirty(m)
脏词过滤。
0（关闭）
SetFilterModal(m)
语气词过滤。
0（关闭）
SetFilterPunc(m)
句号过滤。
0（关闭）
SetFilterEmptyResult(m)
空结果是否回调。
1（不回调）
SetWordInfo(m)
词级/字级时间：0 关 / 1 开 / 2 含标点 / 100 字幕。
0（关闭）
SetWordWithSpace(m)
英文单词间空格输出。
0（关闭）
SetVadSilenceTime(ms)
VAD 静音阈值（240-2000）。
800ms
SetVadLevel(level)
VAD 场景档：0 高召回 / 1 远场过滤。
1
SetNoiseThreshold(v)
VAD 噪声微调（0.0-4.0），覆盖场景档。
未设置
SetMaxSpeakTime(ms)
强制断句时间（5000-90000）。
60000ms
SetInputSampleRate(r)
输入 PCM 采样率，仅8000。
-
SetSpeakerDiarization(m)
说话人分离：0 关 / 1 聚类 / 3 声纹角色。
0（关闭）
SetSpeakerNumber(n)
说话人数量提示（分离开启时生效）。
0（自动）
SetSpeakerRoles(roles)
临时声纹角色（仅模式 3，{RoleName, AudioURL}）。
-
SetVoiceprintIDs(ids)
已注册声纹 ID（仅模式 3）。
-
SetLanguage(lang)
指定识别语言。
自动检测
SetVoiceID(id)
自定义 voice_id（UserSig 自动绑定该值）。
自动 UUID
SetContext(ctx)
识别上下文（text / terms / general）。
-
错误码
数值
说明
4000
音频数据发送过多，请1秒内最多发送3秒音频数据。
注意：
实时识别的效果是“边说边出文字”，1秒内发送的音频数据总时长应为1秒。
4001
参数不合法，具体详情参考 message。
4002
鉴权失败。请检查 sdkappid、usersig 是否已通过首帧消息的 auth 块正确传入，以及签名的 identifier 是否等于当前 voice_id、签名是否有效未过期。
4003
AppID 服务未开通，请在控制台开通服务。
4004
资源包耗尽，请开通后付费或者购买资源包。
4005
账户欠费停止服务，请及时充值。
4006
账号当前调用并发超限。
4007
音频解码失败，请检查上传音频数据格式与调用参数一致。
4008
超时。建连后3秒未发送首帧，或识别过程中15秒未发送音频数据。
4009
客户端连接断开。
4010
客户端上传未知文本消息。首帧 JSON 非法，或 type 非 start。
5000
因机器负载过高、网络抖动等导致失败，请重新发起新识别。
注意：
该问题通常为偶发，少量出现可忽略，发起新识别即可。
5001
同 5000。
5002
同 5000。
SDK 本地错误码：SDK 返回的 error 为 *common.ASRError，其 Code 即服务端错误码。SDK 本地错误使用 10xx 区间，如 1001 本地参数错误、1002 连接失败。

参数	获取位置	说明
SDKAppID	TRTC 控制台 > 应用管理	TRTC 应用 ID，v3 的唯一客户维度。
SecretKey	TRTC 控制台 > 应用概览 > SDK 密钥	用于生成 UserSig，不会传输到网络。

内容	说明
语言种类	支持中文普通话、中文方言、英语，以及日语、韩语、法语等其他语种。
支持行业	通用。
音频属性	采样率：16000Hz 或 8000Hz；采样精度：16bits；声道：单声道（mono）。
音频格式	`1` pcm、`4` speex、`6` silk、`8` mp3、`10` opus（裸 Opus 帧流）、`11` ogg（Ogg 封装，含 .opus/.ogg 文件）、`12` wav、`14` m4a、`16` aac。说明： Opus 是编码格式，实际传输有两种封装，对应不同的 `voice_format`： `10`（裸 Opus 帧流）：音频是连续的 Opus 帧序列，每帧前带2字节小端长度前缀。 `11`（Ogg 封装）：音频是 Ogg 容器文件，文件头前4字节为 `OggS`。常见的 .opus、.ogg 文件都属于此类（容器内部编码可为 Opus 或 Vorbis）。用现成音频文件推流时请选 `11`。判断方法：查看文件前4字节，是 `OggS` 就填 `11`。
请求协议	WSS 协议。
请求地址	`wss://asr.cloud-rtc.com/asr/v3?voice_id=<voice_id>` 鉴权信息通过首帧消息的 `auth` 块传入，URL 上不携带鉴权参数。
响应格式	JSON。
数据发送	每 40ms 发送 40ms 时长（即 1:1 实时率）的数据包，对应 PCM 大小为：8k 采样率640字节，16k 采样率1280字节。单帧不超过256KB。建连后需在3秒内发送首帧；音频数据包之间发送间隔超过15秒，后台将返回错误并主动断开连接。
并发限制	默认单账号（SDKAppID）限制并发数为200路。

字段名	类型	描述
code	Integer	状态码，0 代表正常，非 0 值表示发生错误。
message	String	错误说明。
voice_id	String	音频流全局唯一标识，一个 WebSocket 连接对应一个，用户自己生成（推荐使用 UUID），最长128位。
message_id	String	本 message 唯一 ID。
result	Result	最新语音识别结果，结构见识别结果。
final	Integer	该字段返回1时表示音频流全部识别结束。

字段	类型	必填	说明
sdkappid	String	是	TRTC 应用 ID，取自 credential，SDK 自动填写。
usersig	String	是	TRTC 签名，identifier = 当前 `voice_id`，SDK 按该值签发。计算方式请参见用户鉴权。

参数名	必填	类型	描述
voice_id	否	String	音频流全局唯一标识，一个 WebSocket 连接对应一个，用户自己生成（推荐使用 UUID），最长 128 位。需与 URL 参数一致，或省略。
engine_model_type	是	String	语音识别 2.0（推荐） `bigmodel`：大模型引擎，支持实时说话人分离。语音识别 1.0 基础版引擎：`8k_zh`。标准版引擎：可配置 `8k_zh_large`、`16k_zh_large` 或 `16k_zh_en`。高级版引擎：小语种 ASR 引擎，传参是“16k_具体语种 code”，例如 `16k_vi`（越南语）。
language	否	String	语音识别 2.0（推荐） `bigmodel` 支持 `zh`（中文普通话、中文方言和中英混）、`en`（英语）、`yue`（粤语）和小语种。中文方言：安徽、东北、福建、甘肃、贵州、河北、河南、湖北、湖南、江西、宁夏、山东、陕西、山西、四川、天津、云南、浙江、粤语（香港口音）、粤语（广东口音）、吴语、闽南语。小语种：`ar`（阿拉伯语）、`de`（德语）、`fr`（法语）、`es`（西班牙语）、`pt`（葡萄牙语）、`id`（印尼语）、`it`（意大利语）、`ko`（韩语）、`ru`（俄语）、`th`（泰语）、`vi`（越南语）、`ja`（日语）、`tr`（土耳其语）、`hi`（印地语）、`ms`（马来语）、`nl`（荷兰语）、`sv`（瑞典语）、`da`（丹麦语）、`fi`（芬兰语）、`pl`（波兰语）、`cs`（捷克语）、`fa`（波斯语）、`el`（希腊语）、`ro`（罗马尼亚语）、`hu`（匈牙利语）、`mk`（马其顿语）。语音识别 1.0 基础版：`8k_zh` 支持中文普通话和中文方言。标准版：`8k_zh_large`、`16k_zh_large` 支持中文普通话和中文方言；`16k_zh_en` 支持中文普通话、中文方言、英语和中英混。高级版：`vi`（越南语）、`ja`（日语）、`ko`（韩语）、`id`（印度尼西亚语）、`th`（泰语）、`pt`（葡萄牙语）、`tr`（土耳其语）、`ar`（阿拉伯语）、`es`（西班牙语）、`hi`（印地语）、`fr`（法语）、`ms`（马来语）、`fil`（菲律宾语）、`de`（德语）、`it`（意大利语）、`ru`（俄语）、`sv`（瑞典语）、`da`（丹麦语）、`no`（挪威语）。如果您有更多语言需求，请联系我们评估。说明：当 `engine_model_type` 配置为 `bigmodel`，不填写 `language` 字段时，模型会自动识别语种；使用 SDK 时建议显式指定。
voice_format	否	Integer	语音编码方式，默认 `1`。取值：`1` pcm、`4` speex、`6` silk、`8` mp3、`10` opus（裸 Opus 帧流）、`11` ogg（Ogg 封装，含 .opus/.ogg 文件）、`12` wav、`14` m4a、`16` aac。说明： Opus 是编码格式，实际传输有两种封装，对应不同取值。`10` 裸 Opus 帧流——音频是连续的 Opus 帧序列，每帧前带2字节小端长度前缀；`11` Ogg 封装——音频是 Ogg 容器文件，文件头前4字节为 `OggS`，常见的 .opus、.ogg 文件都属于此类（容器内部编码可为 Opus 或 Vorbis），用现成音频文件推流时请选 `11`。判断方法：查看文件前4字节，是 `OggS` 就填 `11`。实时推流场景建议使用 pcm（16kHz、16bit、单声道）。
input_sample_rate	否	Integer	支持 PCM 格式的 8k 音频在与引擎采样率不匹配的情况下升采样到 16k 后识别，能有效提升识别准确率。仅支持：`8000`。注意：此参数仅适用于 PCM 格式音频，不传入值将维持默认状态，即默认调用的引擎采样率等于 PCM 音频采样率。
needvad	否	Integer	`0` 关闭 vad。 `1` 开启 vad。不传时由引擎决定（Go SDK 默认下发 `1`）。为保证识别效果，如果语音分片长度超过 60 秒，会强制在 60s 断一次，建议音频超过 60s 时开启 vad（人声检测切分功能），提升切分效果。
vad_silence_time	否	Integer	语音断句检测阈值，静音时长超过该阈值会被认为断句（多用在智能客服场景，需配合 `needvad=1` 使用），取值范围 240-2000（默认 800），单位 ms。此参数建议不要随意调整，可能会影响识别效果。
vad_level	否	Integer	VAD 场景档： `0` 高召回。 `1` 远场过滤。默认 `1`。设置 `noise_threshold` 后覆盖本档位。
noise_threshold	否	Float	噪音参数阈值，取值范围 [0.0, 4.0]。对于一些音频片段，取值越大，判定为噪音情况越大；取值越小，判定为人声情况越大。不传时走服务端缺省。
max_speak_time	否	Integer	强制断句功能，取值范围 5000-90000（单位：毫秒），默认值 60000。在连续说话不间断情况下，该参数将实现强制断句（此时结果变成稳态，`slice_type=2`）。例如游戏解说场景，解说员持续不间断解说、无法断句的情况下，将此参数设置为 10000，则将在每10秒收到 `slice_type=2` 的回调。
filter_dirty	否	Integer	是否过滤脏词（目前支持中文普通话引擎）。默认为 `0`。 `0` 不过滤脏词。 `1` 过滤脏词。 `2` 将脏词替换为 `*`。
filter_modal	否	Integer	是否过滤语气词（目前支持中文普通话引擎）。默认为 `0`。 `0` 不过滤语气词。 `1` 部分过滤。 `2` 严格过滤。
filter_punc	否	Integer	是否过滤句末的句号（目前支持中文普通话引擎）。默认为 `0`。 `0` 不过滤句末的句号。 `1` 过滤句末的句号。
filter_empty_result	否	Integer	空结果是否下发： `0` 下发。 `1` 不下发。默认 `1`。
convert_num_mode	否	Integer	是否进行阿拉伯数字智能转换（目前支持中文普通话引擎）： `0` 不转换，直接输出中文数字。 `1` 根据场景智能转换为阿拉伯数字。 `3` 数学模式。默认值为 `1`。
word_info	否	Integer	是否显示词级别时间戳： `0` 不显示。 `1` 显示，不包含标点时间戳。 `2` 显示，包含标点时间戳；`100` 字幕模式。默认 `0`。
word_with_space	否	Integer	英文单词间是否输出空格。默认 `0`。
hotword_id	否	String	热词表 ID，SDKAppID 维度。需先在控制台创建热词表。
hotword_list	否	String	临时热词表：该参数用于提升识别准确率。单个热词限制：“热词\|权重”，单个热词不超过30个字符（最多10个汉字），权重 [1-11] 或者100，例如 “腾讯云\|5” 或 “ASR\|11”；临时热词表限制：多个热词用英文逗号分割，最多支持128个热词，例如 “腾讯云\|10,语音识别\|5,ASR\|11”。注意：热词权重设置为11时，当前热词将升级为超级热词，建议仅将重要且必须生效的热词设置到11，设置过多权重为11的热词将影响整体字准率。热词权重设置为100时，当前热词开启热词增强同音替换功能。举例：热词配置“蜜制\|100”时，与“蜜制”同拼音（mizhi）的“秘制”的识别结果会被强制替换成“蜜制”。因此建议客户根据自己的实际情况开启该功能。建议仅将重要且必须生效的热词设置到100，设置过多权重为100的热词将影响整体字准率。热词不能包含空格。
speaker_diarization	否	Integer	实时说话人分离配置项。 `0` 不开启说话人分离。 `1` 开启说话人分离（匿名聚类）。 `3` 开启说话人分离基础上增加角色认证，需配合 `voiceprint_ids` 或 `speaker_roles` 参数使用。默认值：`0`。注意：取 `1` 或 `3` 时，服务端会强制开启 VAD 并调整 `word_info`。
speaker_number	否	Integer	说话人数量提示，`0` 表示自动检测。两种分离模式都生效。
voiceprint_ids	否	String Array	实时说话人声纹匹配 ID 配置项。该参数值通过声纹注册接口注册获取，参数为数组，最大可支持 32 个声纹。仅 `speaker_diarization=3` 时生效。示例：`["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440002"]`。
speaker_roles	否	Object Array	临时声纹，仅在本次识别中生效，仅 `speaker_diarization=3` 时生效。格式 `[{"audio_url":"...","role_name":"..."}]`。命中后 `role_name` 会回显到识别结果的 `speaker_name`。
context	否	Object	识别上下文：`{"text":"背景文本","terms":["术语"],"general":[{"key":"domain","value":"Meeting"}]}`。

方法	取值	说明
`SetVadLevel(level)`	`0` / `1`	`0` 高召回。 `1` 远场过滤（服务端默认）。
`SetNoiseThreshold(v)`	0.0 - 4.0	噪声抑制微调，值越大抑制越强、召回越低。设置后覆盖 `vad_level` 档位。
`SetVadSilenceTime(ms)`	240 - 2000	静音断句阈值。

方法	说明	默认值
SetVoiceFormat(f)	音频格式。	1（PCM）
SetNeedVad(v)	是否开启 VAD（显式 `0` 会真正下发关闭）。	1（开启）
SetConvertNumMode(m)	数字转换：`0` 不转 / `1` 智能 / `3` 数学（显式 `0` 生效）。	1（智能）
SetHotwordID(id)	热词表 ID（SDKAppID 维度）。	-
SetHotwordList(list)	临时热词列表 `词\|权重,...`。	-
SetFilterDirty(m)	脏词过滤。	0（关闭）
SetFilterModal(m)	语气词过滤。	0（关闭）
SetFilterPunc(m)	句号过滤。	0（关闭）
SetFilterEmptyResult(m)	空结果是否回调。	1（不回调）
SetWordInfo(m)	词级/字级时间：`0` 关 / `1` 开 / `2` 含标点 / `100` 字幕。	0（关闭）
SetWordWithSpace(m)	英文单词间空格输出。	0（关闭）
SetVadSilenceTime(ms)	VAD 静音阈值（240-2000）。	800ms
SetVadLevel(level)	VAD 场景档：`0` 高召回 / `1` 远场过滤。	1
SetNoiseThreshold(v)	VAD 噪声微调（0.0-4.0），覆盖场景档。	未设置
SetMaxSpeakTime(ms)	强制断句时间（5000-90000）。	60000ms
SetInputSampleRate(r)	输入 PCM 采样率，仅8000。	-
SetSpeakerDiarization(m)	说话人分离：`0` 关 / `1` 聚类 / `3` 声纹角色。	0（关闭）
SetSpeakerNumber(n)	说话人数量提示（分离开启时生效）。	0（自动）
SetSpeakerRoles(roles)	临时声纹角色（仅模式 3，`{RoleName, AudioURL}`）。	-
SetVoiceprintIDs(ids)	已注册声纹 ID（仅模式 3）。	-
SetLanguage(lang)	指定识别语言。	自动检测
SetVoiceID(id)	自定义 voice_id（UserSig 自动绑定该值）。	自动 UUID
SetContext(ctx)	识别上下文（`text` / `terms` / `general`）。	-

数值	说明
4000	音频数据发送过多，请1秒内最多发送3秒音频数据。注意：实时识别的效果是“边说边出文字”，1秒内发送的音频数据总时长应为1秒。
4001	参数不合法，具体详情参考 `message`。
4002	鉴权失败。请检查 `sdkappid`、`usersig` 是否已通过首帧消息的 `auth` 块正确传入，以及签名的 identifier 是否等于当前 `voice_id`、签名是否有效未过期。
4003	AppID 服务未开通，请在控制台开通服务。
4004	资源包耗尽，请开通后付费或者购买资源包。
4005	账户欠费停止服务，请及时充值。
4006	账号当前调用并发超限。
4007	音频解码失败，请检查上传音频数据格式与调用参数一致。
4008	超时。建连后3秒未发送首帧，或识别过程中15秒未发送音频数据。
4009	客户端连接断开。
4010	客户端上传未知文本消息。首帧 JSON 非法，或 `type` 非 `start`。
5000	因机器负载过高、网络抖动等导致失败，请重新发起新识别。注意：该问题通常为偶发，少量出现可忽略，发起新识别即可。
5001	同 5000。
5002	同 5000。

WebSocket 接入（新）

本页目录：

接口描述

前提条件

接口要求

业务流程图

接口调用流程

建连阶段

鉴权阶段

auth 字段说明

签名规则

params 参数说明

识别阶段

上传数据

接收消息

识别结果

Word 结构体

说话人分离

speaker_segments 字段

VAD 调优

开发者资源

安装

SDK

SDK 调用示例

初始化凭证

发起实时识别

开启说话人分离

运行示例

配置项

错误码