说明:此接口为 API 2.0 版本,在参数风格、错误码等方面有区别于 API 3.0 版本,请知悉。
1. 接口描述
本接口支持使用者通过 HTTPS POST 方式上传一段音频并在极短时间内同步返回识别结果(通常30分钟音频可在10秒内完成识别),可满足音视频字幕、准实时质检等场景下对语音文件识别时效性的要求。
在使用该接口前,需要在语音识别控制台开通服务,并进入 API 密钥管理页面 新建密钥,生成 AppID、SecretID 和 SecretKey,用于 API 调用时生成签名,签名将用来进行接口鉴权。
2. 接口要求
集成录音识别极速版 API 时,需按照以下要求。
内容 | 说明 |
---|---|
支持语言 | 支持中文普通话、粤语、英语、韩语、日语、泰语、印度尼西亚语、越南语、马来语、菲律宾语、葡萄牙语、土耳其语、阿拉伯语、西班牙语、印地语、法语、德语、上海话、四川话、武汉话、贵阳话、昆明话、西安话、郑州话、太原话、兰州话、银川话、西宁话、南京话、合肥话、南昌话、长沙话、苏州话、杭州话、济南话、天津话、石家庄话、黑龙江话、吉林话、辽宁话。可通过接口参数 engine_type 设置对应语言类型 |
音频格式 | wav、pcm、ogg-opus、speex、silk、mp3、m4a、aac、amr |
使用限制 | 支持100 MB以内且时长不超过2小时的音频文件,如音频时长大于2小时,建议使用 录音文件识别 |
请求协议 | HTTPS |
请求地址 | https://asr.cloud.tencent.com/asr/flash/v1/<appid>?{请求参数} |
接口鉴权 | 签名鉴权机制,详见 签名生成 |
响应格式 | 统一采用 JSON 格式 |
并发限制 | 默认单账号限制并发数为20路,如您有提高并发限制的需求,请 前往购买。 |
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 | 引擎模型类型 识别引擎采用分级计费方案,标记为“大模型版”的引擎适用大模型计费方案,点击这里 查看产品计费说明。 电话场景: 非电话场景: |
voice_format | 是 | String | 音频格式。支持 wav、pcm、ogg-opus、speex、silk、mp3、m4a、aac、amr。 |
timestamp | 是 | Integer | 当前 UNIX 时间戳,如果与当前时间相差超过3分钟,会报签名失败错误。 |
speaker_diarization | 否 | Integer | 是否开启说话人分离(目前支持中文普通话引擎),默认为0,0:不开启,1:开启。 |
hotword_id | 否 | String | 热词表 id。如不设置该参数,自动生效默认热词表;如设置了该参数,那么将生效对应的热词表。 |
customization_id | 否 | String | 自学习模型 id。如设置了该参数,将生效对应的自学习模型。 |
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:显示词时间戳,包含标点;3:标点符号分段,包含每段时间戳,特别适用于字幕场景(包含词级时间、标点、语速值)。 |
first_channel_only | 否 | Integer | 是否只识别首个声道,默认为1。0:识别所有声道;1:识别首个声道。 注意:如识别所有声道,则会按照 声道数*音频时长 来计费,例如时长10秒的双声道文件,如识别所有声道,会按照20秒计费。 |
sentence_max_length | 否 | Integer | 单标点最多字数,取值范围:[6,40]。默认为0,不开启该功能。该参数可用于字幕生成场景,控制单行字幕最大字数。仅支持 8k_zh、16k_zh 引擎。(目前仅支持8k zh/16k zh引擎。) |
hotword_list | 否 | String | 临时热词表:该参数用于提升识别准确率。
|
input_sample_rate | 否 | Interge | 支持 pcm 格式的8k音频在与引擎采样率不匹配的情况下升采样到16k后识别,能有效提升识别准确率。仅支持:8000。如:传入 8000 ,则pcm音频采样率为8k,当引擎选用16k_zh, 那么该8k采样率的 pcm 音频可以在16k_zh引擎下正常识别。 注:此参数仅适用于 pcm 格式音频,不传入值将维持默认状态,即默认调用的引擎采样率等于 pcm 音频采样率。 |
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=125922***
,SecretId= *****Qq1zhZMN8dv0******
为例拼接签名原文,如下:POSTasr.cloud.tencent.com/asr/flash/v1/125922***?engine_type=16k_zh_beta&extra_punc=0&filter_punc=0&first_channel_only=1&hotword_id=584f4d0060d811ed85da525400aec391&reinforce_hotword=0&secretid=*****Qq1zhZMN8dv0******&speaker_diarization=0×tamp=1673426168&voice_format=wav&word_info=1
- 对签名原文使用 SecretKey 进行 HmacSha1 加密,之后再进行 base64 编码。例如对上一步的签名原文,
SecretKey=*****SkqpeHgqmSz*****
,使用 HmacSha1 算法进行加密并做 base64 编码处理:
得到 signature 签名值为:Base64Encode(HmacSha1("POSTasr.cloud.tencent.com/asr/flash/v1/125922***?engine_type=16k_zh_beta&extra_punc=0&filter_punc=0&first_channel_only=1&hotword_id=584f4d0060d811ed85da525400aec391&reinforce_hotword=0&secretid=*****Qq1zhZMN8dv0******&speaker_diarization=0×tamp=1673426168&voice_format=wav&word_info=1", "*****SkqpeHgqmSz*****"))
vLBmoXJ8Oi4YMEuNhpIyrOo+deM=
3.6 请求示例
用户通过 签名生成 的签名为 R53FKwXyJujLC+W2rqJijhmS1a4=,语音数据路径为 /data/test.wav,请求录音识别极速版服务,这里以 curl 请求为例来说明。
curl --data-binary "@/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":"6098aecab9c686fbfd35adb0",
"code":0,
"message":"",
"audio_duration":2386,
"flash_result":[
{
"text":"便宜云服务器租用智能语音欢迎您。",
"channel_id":0,
"sentence_list":[
{
"text":"便宜云服务器租用智能语音欢迎您。",
"start_time":0,
"end_time":2386,
"speaker_id":0,
"word_list":[
{
"word":"便宜云服务器租用",
"start_time":0,
"end_time":780,
"stable_flag":1
},
{
"word":"智能语音",
"start_time":780,
"end_time":1590,
"stable_flag":1
},
{
"word":"欢迎",
"start_time":1590,
"end_time":1950,
"stable_flag":1
},
{
"word":"您",
"start_time":1950,
"end_time":2250,
"stable_flag":1
}
]
}
]
}
]
}
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 | 音频识别超时,偶现可以忽略,重复出现请提交工单 |