实时音视频一句话识别（新）

接口描述
本接口用于对60秒之内的短音频文件进行识别。
音频格式支持 wav、pcm、ogg-opus、mp3、m4a。
请求方法为 HTTP POST，Content-Type 为 application/json; charset=utf-8。
说明：
2026 年 9 月 24 日起新用户请使用本文档接入 v3 新版接口。
已接入旧版 一句话识别 v2 协议接口的用户可跳转 一句话识别（旧） 查看相关说明文档。
前提条件
需要准备两个凭证：SDKAppID 与 SecretKey。
参数
获取位置
说明
SDKAppID
﻿TRTC 控制台 > 应用管理
TRTC 应用 ID，v3 的唯一客户维度。
SecretKey
﻿TRTC 控制台 > 应用概览 > SDK 密钥
用于生成 UserSig，不会传输到网络。
接口要求
内容
说明
语言种类
支持中文普通话、中文方言、英语，以及日语、韩语、法语等小语种。
支持行业
通用。
音频属性
采样率：16000Hz（pcm 格式例外，可通过 input_sample_rate 参数支持 8000Hz，详见输入参数说明）；采样精度：16bits；声道：单声道（mono）。
音频格式
wav、pcm、ogg-opus、mp3、m4a。
请求协议
https 协议。
请求地址
国内站 https://asr.cloud-rtc.com/v3/transcribe。鉴权信息通过请求 body 的 auth 块传入，URL 不携带 query 参数。
响应格式
JSON，扁平结构。
数据发送
支持本地语音文件上传和语音 URL 上传两种请求方式，音频时长不能超过60s，音频文件大小不能超过3MB。
并发限制
默认单账号限制并发数为30次每秒。
说明：
同一 SDKAppID 下，直接接入 ASR、AI 对话、AI 转录/翻译等所有实时语音识别场景共享该并发池，即各类型的并发路数合计不超过账号上限。一句话识别与录音文件识别独立计算，不占用实时识别并发额度。如您有更多并发需求，请 联系我们。
业务流程图
﻿
接口调用流程
请求格式
客户端发起 HTTP POST 请求，请求 URL 为：https://asr.cloud-rtc.com/v3/transcribe。
请求 body 为对称结构，格式为 json：
{
  "auth": {"sdkappid": "1400000001", "usersig": "eJw...", "request_id": "req-uuid"},
  "params": {"engine_model_type": "bigmodel", "language": "zh", "source_type": 1, "voice_format": "wav", "data": "xxxxxxxx", "data_len": 8}
}
说明：
v3 不再使用 X-TRTC-SdkAppId / X-TRTC-UserSig 请求 header，也不再在 URL 上携带 AppId / RequestId。鉴权信息全部位于 body 的 auth 块内。
请求参数（auth）
每次 HTTP 请求是一个独立事务，request_id 既是单次请求 ID、也是签名 identifier。
参数名
必填
类型
描述
sdkappid
是
String
TRTC 应用 ID，获取方式见 应用基本信息。SDK 自动填写。示例值：1400000001。
usersig
是
String
TRTC 签名，计算及使用请参见 用户鉴权，其中的 UserID 等于本次请求的 request_id。
request_id
是
String
全局请求唯一 ID（uuid），该参数用来生成请求 UserSig。SDK 每次请求自动生成，响应原样回显。SDK 不支持自定义。
签名规则
1. 未调用 credential.SetUserSig() 时，SDK 使用 SDKAppID + SecretKey 本地生成签名，有效期86400秒，且每次请求都重新生成，长跑服务无需自行管理过期。
2. 调用 credential.SetUserSig(sig) 传入固定签名后，SDK 不再生成也不再刷新。服务端使用当前 identifier（离线为 request_id）验签，因此签名必须用同一个 identifier 签发。
3. 签名与站点绑定。SetSite(common.SiteIntl) 决定 host 与验签集群，国际站凭证不可用于国内站，反之亦然。
4. SecretKey 不会传输到网络，签名只用于服务端验签。
输入参数（params）
一句话识别的请求消息体，格式为 json。
参数名
必填
类型
描述
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 时建议显式指定。
source_type
是
Integer
语音数据来源：
0 语音 URL。
1 语音数据（post body）。
voice_format
是
String
识别音频的音频格式，支持 wav、pcm、ogg-opus、mp3、m4a。
url
否
String
语音的 URL 地址，需要公网环境浏览器可下载。当 source_type 值为0时须填写该字段，为1时不填。音频时长不能超过60s，音频文件大小不能超过3MB。
data
否
String
语音数据，当 source_type 值为1（本地语音数据上传）时必须填写，当 source_type 值为0（语音 URL 上传）可不写。必须使用 Base64 编码（采用 Python 语言时注意读取文件应该为 string 而不是 byte，以 byte 格式读取后要 decode()。编码后的数据不可带有回车换行符）。音频时长不能超过60s，音频文件大小不能超过3MB（Base64 编码后）。
data_len
否
Integer
数据长度，单位为字节。当 source_type 值为1（本地语音数据上传）时必须填写，当 source_type 值为0（语音 URL 上传）可不写（此数据长度为数据未进行 Base64 编码时的数据长度）。
noise_threshold
否
Float
噪音参数阈值，取值范围：[0.0, 4.0]。对于一些音频片段，取值越大，判定为噪音情况越大；取值越小，判定为人声情况越大。
word_info
否
Integer
是否显示词级别时间戳：
0 不显示。
1 显示，不包含标点时间戳。
2 显示，包含标点时间戳。默认值为 0。
filter_dirty
否
Integer
是否过滤脏词（中文普通话）：
0 不过滤脏词。
1 过滤脏词。
2 将脏词替换为 *。
默认值为 0。
filter_modal
否
Integer
是否过滤语气词（中文普通话）：
0 不过滤语气词。
1 部分过滤。
2 严格过滤。
默认值为 0。
filter_punc
否
Integer
是否过滤标点符号（中文普通话）：
0 不过滤。
1 过滤句末标点。
2 过滤所有标点。
默认值为 0。
convert_num_mode
否
Integer
是否进行阿拉伯数字智能转换：
0 不转换，直接输出中文数字。
1 根据场景智能转换为阿拉伯数字。
3 数学模式。
默认值为 1。
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的热词将影响整体字准率。热词不能包含空格。
customization_id
否
String
自学习模型 ID。
input_sample_rate
否
Integer
支持 pcm 格式的8000音频在与引擎采样率不匹配的情况下升采样到16000后识别，能有效提升识别准确率。仅支持：8000。如传入8000，则 pcm 音频采样率为8000，当引擎选用 16k_zh 时，该8000采样率的 pcm 音频可以在 16k_zh 引擎下正常识别。
注意：
此参数仅适用于 pcm 格式音频，不传入值将维持默认状态，即默认调用的引擎采样率等于 pcm 音频采样率。
needvad
否
Integer
三态字段：不传走服务端默认；
0 关闭 vad。
1 开启 vad。
vad_silence_time
否
Integer
三态字段：不传走服务端默认（800）。语音断句检测阈值，单位 ms，取值范围240-2000。
speaker_diarization
否
Integer
说话人分离：
0 不开启。
1 开启说话人分离（匿名聚类）。
3 开启说话人分离基础上增加角色认证。
默认值 0。
speaker_number
否
Integer
说话人数量提示，0 表示自动检测。
context
否
Object
识别上下文：{"text":"背景文本","terms":["术语"],"general":[{"key":"domain","value":"Meeting"}]}。
说明：
context 的消费方式与引擎能力相关：大模型类引擎可使用 text / terms / general；传统引擎仅把 terms 降级为热词使用。
响应格式
响应消息为 json 格式，扁平结构，所有返回字段位于顶层，不再有 Response 外壳。
参数名
类型
描述
code
Integer
状态码，0 代表正常，非 0 值表示发生错误。
message
String
错误说明。
request_id
String
本次请求的 request_id，与请求 auth.request_id 一致。定位问题时需要提供该次请求的 request_id。
result
String
识别结果。
audio_duration
Integer
请求的音频时长，单位为 ms。
language
String
识别语言。
language_b47
String
识别语言标识。
word_size
Integer
词时间戳列表的长度。
注意：
此字段可能返回 null，表示取不到有效值。
word_list
Array of Word
词时间戳列表，需 word_info != 0。
注意：
此字段可能返回 null，表示取不到有效值。
Word 定义为 word_list 数组的元素结构，位于 word_list[] 之内：
名称
类型
描述
word
String
词结果。
start_time
Integer
词在音频中的开始时间。
end_time
Integer
词在音频中的结束时间。
注意：
v3 离线接口鉴权失败返回的是 HTTP 200 + body {"code":4002}，不是 HTTP 4xx。判断请求成败请以 body 的 code 为准，不要只看 HTTP 状态码。SDK 已处理该情况，code != 0 时会返回携带该 code 的 error。
示例
用户通过 source_type=1 请求一句话识别，请求如下：
请求网址：
https://asr.cloud-rtc.com/v3/transcribe
请求 body：
{
    "auth": {
        "sdkappid": "1400188366",
        "usersig": "eJw...",
        "request_id": "2f5e8263-a23b-4e65-be22-6b7c19bd4064"
    },
    "params": {
        "engine_model_type": "bigmodel",
        "language": "zh",
        "source_type": 1,
        "voice_format": "wav",
        "data": "xxxxxxxx",
        "data_len": 8,
        "word_info": 1
    }
}
响应结果：
{
    "code": 0,
    "message": "success",
    "request_id": "2f5e8263-a23b-4e65-be22-6b7c19bd4064",
    "result": "我们能接受的范围内。",
    "audio_duration": 1840,
    "language": "zh",
    "word_size": 3,
    "word_list": [
        {"word": "我们", "start_time": 120, "end_time": 480},
        {"word": "能接受的", "start_time": 480, "end_time": 1200},
        {"word": "范围内", "start_time": 1200, "end_time": 1840}
    ]
}
注意：
未传 word_info 时，响应中不返回 word_size 与 word_list。
开发者资源
安装
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) // 国际站；不调用则走国内站
发起一句话识别
recognizer := v3.NewSentenceRecognizer(credential)
data, _ := os.ReadFile("audio.pcm")
resp, err := recognizer.RecognizeDataWithOptions(data, &v3.TranscribeRequest{
    EngineModelType: "bigmodel",
    VoiceFormat:     "pcm",
    Language:        "zh",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Result, resp.AudioDuration, resp.WordList)
注意：
请确保已通过 import 语句导入所需的包，例如 import ("os", "log", "fmt")。
运行示例
cd examples/v3_sentence_asr
go run main.go bigmodel -f ../test.pcm -word-info 1
﻿
# 查看所有选项
go run main.go -h
错误码
v3 全部使用数字错误码，返回在 body 的 code 字段中。
数值
说明
400
音频发送失败、音频为空或请求消息体格式错误。
413
音频超限。
4001
参数不合法，具体详情参考 message。
4002
鉴权失败。请检查 sdkappid、usersig 是否已通过 body 的 auth 块正确传入，以及签名的 identifier 是否等于本次请求的 request_id。
4003
AppID 服务未开通，请在控制台开通服务。
4004
资源包耗尽，请开通后付费或者购买资源包。
4005
账户欠费停止服务，请及时充值。
4006
账号当前调用并发超限。
4007
音频解码失败，请检查上传音频数据格式是否与调用参数一致。
5000
因机器负载过高、网络抖动等导致失败，请重新发起新识别。
注意：
该问题通常为偶发，少量出现可忽略，发起新识别即可。
5001
同 5000。
5002
同 5000。
HTTP 状态码与 code 的对应关系：
HTTP 状态码
场景
code
400
参数错误
4001
200
鉴权失败
4002
429
并发超限
4006
413
请求 body 过大
——
503
调度失败
5000 / 5001 / 5002
注意：
鉴权失败是 HTTP 200，不是 4xx。一律以 body 的 code 为准。
SDK 本地错误码：SDK 返回的 error 为 *common.ASRError，其 Code 即服务端错误码。SDK 本地错误使用 10xx 区间，如 1001 本地参数错误、1002 连接失败。

一句话识别（新）

本页目录：

接口描述

前提条件

接口要求

业务流程图

接口调用流程

请求格式

请求参数（auth）

签名规则

输入参数（params）

响应格式

示例

开发者资源

安装

SDK

SDK 调用示例

初始化凭证

发起一句话识别

运行示例

错误码

v3 全部使用数字错误码，返回在 body 的 `code` 字段中。

HTTP 状态码与 `code` 的对应关系：

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

内容	说明
语言种类	支持中文普通话、中文方言、英语，以及日语、韩语、法语等小语种。
支持行业	通用。
音频属性	采样率：16000Hz（pcm 格式例外，可通过 `input_sample_rate` 参数支持 8000Hz，详见输入参数说明）；采样精度：16bits；声道：单声道（mono）。
音频格式	wav、pcm、ogg-opus、mp3、m4a。
请求协议	https 协议。
请求地址	国内站 `https://asr.cloud-rtc.com/v3/transcribe`。鉴权信息通过请求 body 的 `auth` 块传入，URL 不携带 query 参数。
响应格式	JSON，扁平结构。
数据发送	支持本地语音文件上传和语音 URL 上传两种请求方式，音频时长不能超过60s，音频文件大小不能超过3MB。
并发限制	默认单账号限制并发数为30次每秒。

参数名	必填	类型	描述
sdkappid	是	String	TRTC 应用 ID，获取方式见应用基本信息。SDK 自动填写。示例值：1400000001。
usersig	是	String	TRTC 签名，计算及使用请参见用户鉴权，其中的 UserID 等于本次请求的 `request_id`。
request_id	是	String	全局请求唯一 ID（uuid），该参数用来生成请求 UserSig。SDK 每次请求自动生成，响应原样回显。SDK 不支持自定义。

名称	类型	描述
word	String	词结果。
start_time	Integer	词在音频中的开始时间。
end_time	Integer	词在音频中的结束时间。

数值	说明
400	音频发送失败、音频为空或请求消息体格式错误。
413	音频超限。
4001	参数不合法，具体详情参考 `message`。
4002	鉴权失败。请检查 `sdkappid`、`usersig` 是否已通过 body 的 `auth` 块正确传入，以及签名的 identifier 是否等于本次请求的 `request_id`。
4003	AppID 服务未开通，请在控制台开通服务。
4004	资源包耗尽，请开通后付费或者购买资源包。
4005	账户欠费停止服务，请及时充值。
4006	账号当前调用并发超限。
4007	音频解码失败，请检查上传音频数据格式是否与调用参数一致。
5000	因机器负载过高、网络抖动等导致失败，请重新发起新识别。注意：该问题通常为偶发，少量出现可忽略，发起新识别即可。
5001	同 5000。
5002	同 5000。

HTTP 状态码	场景	code
400	参数错误	4001
200	鉴权失败	4002
429	并发超限	4006
413	请求 body 过大	——
503	调度失败	5000 / 5001 / 5002