说明:此接口为 API 2.0 版本,在参数风格、错误码等方面有区别于 API 3.0 版本,请知悉。
1. 接口描述
本接口支持使用者通过 HTTPS POST 方式上传一段音频并在极短时间内同步返回识别结果,可满足音视频字幕、准实时质检等场景下对语音文件识别时效性的要求。
在使用该接口前,需要在语音识别控制台开通服务,并进入 API 密钥管理页面 新建密钥,生成 AppID、SecretID 和 SecretKey,用于 API 调用时生成签名,签名将用来进行接口鉴权。
2. 接口要求
集成录音识别极速版 API 时,需按照以下要求。
内容 | 说明 |
---|---|
支持语言 | 中文普通话 |
音频格式 | wav、pcm、ogg-opus、speex、silk、mp3、m4a、aac |
使用限制 | 支持100MB以内音频文件的识别 |
请求协议 | HTTPS |
请求地址 | https://asr.cloud.tencent.com/asr/flash/v1/<appid>?{请求参数} |
接口鉴权 | 签名鉴权机制,详见 签名生成 |
响应格式 | 统一采用 JSON 格式 |
并发限制 | 默认单账号限制并发数为3路,如您有提高并发限制的需求,请 提工单 进行咨询。 |
3. 接口调用说明
本接口为 HTTPS 同步调用,包含请求 Header、请求 URL、请求 Body、响应 Response。
- 请求 Header:包含 Host、签名串等信息
- 请求 URL:包含请求的所有参数
- 请求 Body:包含音频原始数据
- 响应 Response:返回识别结果,为 JSON 结构
以下为详细说明。
3.1 请求 Header 说明
包括 Host、Authorization、Content-Type、Content-Length 四个参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Host | 是 | String | 语音识别服务域名,固定为 asr.cloud.tencent.com |
Authorization | 是 | String | 用户的签名字符串,用于鉴权。详见 签名生成 |
Content-Type | 是 | String | application/octet-stream |
Content-Length | 是 | Integer | 请求长度,此处对应语音数据字节数,单位:字节 |
3.2 请求参数说明
URL 中的请求参数可包含如下参数:
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
AppId | 是 | Integer | 用户在腾讯云注册账号的 AppId,可以进入 API 密钥管理页面 获取。 |
secretid | 是 | String | 用户在腾讯云注册账号 AppId 对应的 SecretId,可以进入 API 密钥管理页面 获取。 |
engine_type | 是 | String | 引擎模型类型。 8k_zh:8k 中文普通话通用; 16k_zh:16k 中文普通话通用; 16k_zh_video:16k 音视频领域。 |
voice_format | 是 | String | 音频格式。支持 wav、pcm、ogg-opus、speex、silk、mp3、m4a、aac。 |
timestamp | 是 | Integer | 当前 UNIX 时间戳,如果与当前时间相差超过3分钟,会报签名失败错误。 |
speaker_diarization | 否 | Integer | 是否开启说话人分离(目前支持中文普通话引擎),默认为0,0:不开启,1:开启。 |
filter_dirty | 否 | Integer | 是否过滤脏词(目前支持中文普通话引擎),默认为0。0:不过滤脏词;1:过滤脏词;2:将脏词替换为 *。 |
filter_modal | 否 | Integer | 是否过滤语气词(目前支持中文普通话引擎),默认为0。0:不过滤语气词;1:部分过滤;2:严格过滤。 |
filter_punc | 否 | Integer | 是否过滤标点符号(目前支持中文普通话引擎),默认为0。0:不过滤,1:过滤句末标点,2:过滤所有标点。 |
convert_num_mode | 否 | Integer | 是否进行阿拉伯数字智能转换,默认为1。0:全部转为中文数字;1:根据场景智能转换为阿拉伯数字。 |
word_info | 否 | Integer | 是否显示词级别时间戳,默认为0。0:不显示;1:显示,不包含标点时间戳,2:显示,包含标点时间戳。 |
first_channel_only | 否 | Integer | 是否只识别首个声道,默认为1。0:识别所有声道;1:识别首个声道。 |
3.3 请求 Body 说明
请求 Body 中包含音频原始数据,最大不能超过100MB。
3.4 响应结果说明
HTTPS 请求返回的响应为 JSON 结构,具体结构说明如下:
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 0:正常,其他,发生错误 |
message | String | code 非0时,message 中会有错误消息 |
request_id | String | 请求唯一标识,请您记录该值,以便排查错误 |
audio_duration | Integer | 音频时长,单位为毫秒 |
flash_result | []Result | 声道识别结果列表 |
Result 结构为:
参数 | 类型 | 描述 |
---|---|---|
channel_id | Integer | 声道标识,从0开始,对应音频声道数 |
text | String | 声道音频完整识别结果 |
sentence_list | []Sentence | 句子/段落级别的识别结果列表 |
Sentence 结构为:
参数 | 类型 | 描述 |
---|---|---|
text | String | 句子/段落级别文本 |
start_time | Integer | 开始时间 |
end_time | Integer | 结束时间 |
speaker_id | Integer | 说话人 Id(请求中如果设置了 speaker_diarization,可以按照 speaker_id 来区分说话人) |
word_list | []Word | 词级别的识别结果列表 |
Word 结构为:
参数 | 类型 | 描述 |
---|---|---|
word | String | 词级别文本 |
start_time | Integer | 开始时间 |
end_time | Integer | 结束时间 |
3.5 签名生成说明
- 对所有参数按字典序进行排序,拼接 POST 串 + 请求 URL 作为签名原文,这里以 Appid=1259228442,SecretId=AKIDoQq1zhZMN8dv0psmvud6OUKuGPO7pu0r 为例拼接签名原文,如下:
POSTasr.cloud.tencent.com/asr/flash/v1/1259228442?convert_num_mode=1&engine_type=16k_zh&filter_dirty=0&filter_modal=0&filter_punc=0&first_channel_only=1&hotword_id=&secretid=AKIDoQq1zhZMN8dv0psmvud6OUKuGPO7pu0r&speaker_diarization=0×tamp=1609560089&voice_format=wav&word_info=0
- 对签名原文使用 SecretKey 进行 HmacSha1 加密,之后再进行 base64 编码。例如对上一步的签名原文, SecretKey=kFpwoX5RYQ2SkqpeHgqmSzHK7h3A2fni,使用 HmacSha1 算法进行加密并做 base64 编码处理:
得到 signature 签名值为:Base64Encode(HmacSha1("POSTasr.cloud.tencent.com/asr/flash/v1/1259228442?convert_num_mode=1&engine_type=16k_zh&filter_dirty=0&filter_modal=0&filter_punc=0&first_channel_only=1&hotword_id=&secretid=AKIDoQq1zhZMN8dv0psmvud6OUKuGPO7pu0r&speaker_diarization=0×tamp=1609560089&voice_format=wav&word_info=0", "kFpwoX5RYQ2SkqpeHgqmSzHK7h3A2fni"))
R53FKwXyJujLC+W2rqJijhmS1a4=
3.6 请求示例
用户通过 签名生成 的签名为 HepdTRX6u155qIPKNKC+3U0j1N0=,语音数据路径为 /data/test.wav,请求录音识别极速版服务,这里以 curl 请求为例来说明。
curl --data "@/data/test.wav" -H "Authorization:R53FKwXyJujLC+W2rqJijhmS1a4=" -X POST "https://asr.cloud.tencent.com/asr/flash/v1/1259228442?convert_num_mode=1&engine_type=16k_zh&filter_dirty=0&filter_modal=0&filter_punc=0&first_channel_only=1&hotword_id=&secretid=AKIDoQq1zhZMN8dv0psmvud6OUKuGPO7pu0r&speaker_diarization=0×tamp=1609560089&voice_format=wav&word_info=0"
3.7 返回示例
{
"request_id":"5fef0ff60a0f0c5bcec31bb0",
"code":0,
"message":"",
"audio_duration":4060,
"flash_result":[
{
"text":"北京科技馆。",
"channel_id":0,
"sentence_list":[
{
"text":"北京科技馆。",
"start_time":1040,
"end_time":3100,
"speaker_id":0
}
]
}
]
}
4. 开发者资源
SDK
- Tencent Cloud Speech SDK for Python
- Tencent Cloud Speech SDK for Go
- Tencent Cloud Speech SDK for Java
SDK 调用示例
5. 错误码说明
数值 | 说明 |
---|---|
4001 | 参数不合法,具体详情参考 message |
4002 | 鉴权失败 |
4003 | AppID 服务未开通,请在控制台开通服务 |
4004 | 无可使用的免费额度 |
4005 | 账户欠费停止服务,请及时充值 |
4006 | 账号当前调用并发超限 |
4007 | 音频解码失败,请检查上传音频数据格式与调用参数一致 |
4008 | 客户端数据上传超时 |
4009 | 客户端连接断开 |
4010 | 客户端上传未知文本消息 |
4011 | 音频数据太大 |
4012 | 音频数据为空 |
5001 | 后台错误,请重试 |
5002 | 音频识别失败,偶现可以忽略,重复出现请提交工单 |
5003 | 音频识别超时,偶现可以忽略,重复出现请提交工单 |