1. 接口描述
接口请求域名: asr.tencentcloudapi.com 。
本接口可对较长的录音文件进行识别。如希望直接使用带界面的语音识别产品,请访问产品体验中心。产品计费标准请查阅 计费概述(在线版)
? 接口默认限频:20次/秒。此处仅限制任务提交频次,与识别结果返回时效无关
? 返回时效:异步回调,非实时返回。最长3小时返回识别结果,大多数情况下,1小时的音频1-3分钟即可完成识别。请注意:上述返回时长不含音频下载时延,且30分钟内发送超过1000小时录音或2万条任务的情况除外
? 音频格式:wav、mp3、m4a、flv、mp4、wma、3gp、amr、aac、ogg-opus、flac
? 支持语言:在本页面上搜索 EngineModelType,或前往 产品功能 查看
? 音频提交方式:本接口支持音频 URL 、本地音频文件两种请求方式。推荐使用 便宜云服务器租用COS 来存储、生成URL并提交任务,此种方式将不产生外网和流量下行费用,可节约成本、提升任务速度(COS桶权限需要设置公有读私有写,或URL设置外部可访问)
? 音频限制:音频 URL 时长不能大于5小时,文件大小不超过1GB;本地音频文件不能大于5MB
? 如何获取识别结果:支持回调或轮询的方式获取结果,具体请参考 录音文件识别结果查询
? 识别结果有效时间:识别结果在服务端保存24小时
? 签名方法参考 公共参数 中签名方法 v3
默认接口请求频率限制:20次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreateRecTask。 |
Version | 是 | String | 公共参数,本接口取值:2019-06-14。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
EngineModelType | 是 | String | 引擎模型类型 识别引擎采用分级计费方案,标记为“大模型版”的引擎适用大模型计费方案,点击这里 查看产品计费说明 电话通讯场景引擎: 注意:电话通讯场景,请务必使用以下8k引擎 ? 8k_zh:中文电话通讯; ? 8k_en:英文电话通讯; ? 8k_zh_large:普方大模型引擎【大模型版】。当前模型同时支持中文、多种中文方言等语言的识别,模型参数量极大,语言模型性能增强,针对电话音频中各类场景、各类中文方言的识别准确率极大提升,点击这里 对比常规版本与普方大模型版本的识别效果; 注意:如您有电话通讯场景识别需求,但发现需求语种仅支持16k,可将8k音频传入下方16k引擎,亦能获取识别结果。但16k引擎并非基于电话通讯数据训练,无法承诺此种调用方式的识别效果,需由您自行验证识别结果是否可用 通用场景引擎: 注意:除电话通讯场景以外的其它识别场景,请务必使用以下16k引擎 ? 16k_zh:中文普通话通用引擎,支持中文普通话和少量英语,使用丰富的中文普通话语料训练,覆盖场景广泛,适用于除电话通讯外的所有中文普通话识别场景; ? 16k_zh_large:普方英大模型引擎【大模型版】。当前模型同时支持中文、英文、多种中文方言等语言的识别,模型参数量极大,语言模型性能增强,针对噪声大、回音大、人声小、人声远等低质量音频的识别准确率极大提升,点击这里 对比中文普通话常规版本与普方英大模型版本的识别效果; ? 16k_multi_lang:多语种大模型引擎【大模型版】。当前模型同时支持英语、日语、韩语、阿拉伯语、菲律宾语、法语、印地语、印尼语、马来语、葡萄牙语、西班牙语、泰语、土耳其语、越南语、德语的识别,可实现15个语种的自动识别(句子/段落级别); ? 16k_zh_dialect:中文普通话+多方言混合引擎,除普通话外支持23种方言(上海话、四川话、武汉话、贵阳话、昆明话、西安话、郑州话、太原话、兰州话、银川话、西宁话、南京话、合肥话、南昌话、长沙话、苏州话、杭州话、济南话、天津话、石家庄话、黑龙江话、吉林话、辽宁话); ? 16k_en:英语; ? 16k_yue:粤语; ? 16k_zh-PY:中英粤混合引擎,使用一个引擎同时识别中文普通话、英语、粤语三个语言; ? 16k_ja:日语; ? 16k_ko:韩语; ? 16k_vi:越南语; ? 16k_ms:马来语; ? 16k_id:印度尼西亚语; ? 16k_fil:菲律宾语; ? 16k_th:泰语; ? 16k_pt:葡萄牙语; ? 16k_tr:土耳其语; ? 16k_ar:阿拉伯语; ? 16k_es:西班牙语; ? 16k_hi:印地语; ? 16k_fr:法语; ? 16k_zh_medical:中文医疗引擎; ? 16k_de:德语; 示例值:16k_zh |
ChannelNum | 是 | Integer | 识别声道数 1:单声道(16k音频仅支持单声道,请勿设置为双声道); 2:双声道(仅支持8k电话音频,且双声道应分别为通话双方) 注意: ? 16k音频:仅支持单声道识别,需设置ChannelNum=1; ? 8k电话音频:支持单声道、双声道识别,建议设置ChannelNum=2,即双声道。双声道能够物理区分说话人、避免说话双方重叠产生的识别错误,能达到最好的说话人分离效果和识别效果。设置双声道后,将自动区分说话人,因此无需再开启说话人分离功能,相关参数(SpeakerDiarization、SpeakerNumber)使用默认值即可 示例值:1 |
ResTextFormat | 是 | Integer | 识别结果返回样式 0:基础识别结果(仅包含有效人声时间戳,无词粒度的详细识别结果); 1:基础识别结果之上,增加词粒度的详细识别结果(包含词级别时间戳、语速值,不含标点); 2:基础识别结果之上,增加词粒度的详细识别结果(包含词级别时间戳、语速值和标点); 3:基础识别结果之上,增加词粒度的详细识别结果(包含词级别时间戳、语速值和标点),且识别结果按标点符号分段,适用字幕场景; 4:【增值付费功能】基础识别结果之上,增加词粒度的详细识别结果(包含词级别时间戳、语速值和标点),且识别结果按nlp语义分段,适用会议、庭审记录转写等场景,仅支持8k_zh/16k_zh引擎 5:【增值付费功能】基础识别结果之上,增加词粒度的详细识别结果(包含词级别时间戳、语速值和标点),并输出口语转书面语转写结果,该结果去除语气词、重复词、精简冗余表达,并修正发言人口误,实现口语转书面语的效果,适用于线上、线下会议直接总结为书面会议纪要的场景,仅支持8k_zh/16k_zh引擎 注意: 如果传入参数值4,需确保账号已购买语义分段资源包,或账号开启后付费;若当前账号已开启后付费功能,并传入参数值4,将自动计费 如果传入参数值5,需确保账号已购买口语转书面语资源包,或账号开启后付费;若当前账号已开启后付费功能,并传入参数值5,将自动计费自动计费 示例值:0 |
SourceType | 是 | Integer | 音频数据来源 0:音频URL; 1:音频数据(post body) 示例值:0 |
Data | 否 | String | 音频数据base64编码 当 SourceType 值为 1 时须填写该字段,为 0 时不需要填写 注意:音频数据要小于5MB(含) |
DataLen | 否 | Integer | 数据长度(此数据长度为数据未进行base64编码时的长度) |
Url | 否 | String | 音频URL的地址(需要公网环境浏览器可下载) 当 SourceType 值为 0 时须填写该字段,为 1 时不需要填写 注意: 1. 请确保录音文件时长在5个小时(含)之内,否则可能识别失败; 2. 请保证文件的下载速度,否则可能下载失败 示例值:https://audio.cos.ap-guangzhou.myqcloud.com/example.wav |
CallbackUrl | 否 | String | 回调 URL 用户自行搭建的用于接收识别结果的服务URL 回调格式和内容详见:录音识别回调说明 注意: - 如果用户使用轮询方式获取识别结果,则无需提交该参数 - 建议在回调URL中带上您的业务ID等信息,以便处理业务逻辑 |
SpeakerDiarization | 否 | Integer | 是否开启说话人分离 0:不开启; 1:开启(仅支持以下引擎:8k_zh/16k_zh/16k_ms/16k_en/16k_id/16k_zh_large/16k_zh_dialect,且ChannelNum=1时可用); 默认值为 0 注意: 8k双声道电话音频请按 ChannelNum 识别声道数 的参数描述使用默认值 示例值:0 |
SpeakerNumber | 否 | Integer | 说话人分离人数 需配合开启说话人分离使用,不开启无效,取值范围:0-10 0:自动分离(最多分离出20个人); 1-10:指定人数分离; 默认值为 0 示例值:0 |
HotwordId | 否 | String | 热词表id 如不设置该参数,将自动生效默认热词表; 如设置该参数,将生效对应id的热词表; 点击这里查看热词表配置方法 |
CustomizationId | 否 | String | 自学习定制模型 id 如设置了该参数,将生效对应id的自学习定制模型; 点击这里查看自学习定制模型配置方法 |
EmotionRecognition | 否 | Integer | 【增值付费功能】情绪识别能力(目前仅支持16k_zh,8k_zh) 0:不开启; 1:开启情绪识别,但不在文本展示情绪标签; 2:开启情绪识别,并且在文本展示情绪标签(该功能需要设置ResTextFormat 大于0) 默认值为0 支持的情绪分类为:高兴、伤心、愤怒 注意: 1. 本功能为增值服务,需将参数设置为1或2时方可按对应方式生效; 2. 如果传入参数值1或2,需确保账号已购买情绪识别资源包,或账号开启后付费;若当前账号已开启后付费功能,并传入参数值1或2,将自动计费); 3. 参数设置为0时,无需购买资源包,也不会消耗情绪识别对应资源 示例值:0 |
EmotionalEnergy | 否 | Integer | 情绪能量值 取值为音量分贝值/10,取值范围:[1,10],值越高情绪越强烈 0:不开启; 1:开启; 默认值为0 示例值:0 |
ConvertNumMode | 否 | Integer | 阿拉伯数字智能转换(目前支持中文普通话引擎) 0:不转换,直接输出中文数字; 1:根据场景智能转换为阿拉伯数字; 3:打开数学相关数字转换(如:阿尔法转写为α); 默认值为 1 示例值:0 |
FilterDirty | 否 | Integer | 脏词过滤(目前支持中文普通话引擎) 0:不过滤脏词; 1:过滤脏词; 2:将脏词替换为 * ; 默认值为 0 示例值:0 |
FilterPunc | 否 | Integer | 标点符号过滤(目前支持中文普通话引擎) 0:不过滤标点; 1:过滤句末标点; 2:过滤所有标点; 默认值为 0 示例值:0 |
FilterModal | 否 | Integer | 语气词过滤(目前支持中文普通话引擎) 0:不过滤语气词; 1:过滤部分语气词; 2:严格过滤语气词; 默认值为 0 示例值:0 |
SentenceMaxLength | 否 | Integer | 单标点最多字数(目前支持中文普通话引擎) 可控制单行字幕最大字数,适用于字幕生成场景,取值范围:[6,40] 0:不开启该功能; 默认值为0 注意:需设置ResTextFormat为3,解析返回的ResultDetail列表,通过结构中FinalSentence获取单个标点断句结果 示例值:0 |
Extra | 否 | String | 附加参数(该参数无意义,忽略即可) |
HotwordList | 否 | String | 临时热词表:该参数用于提升识别准确率。 - 单个热词限制:"热词|权重",单个热词不超过30个字符(最多10个汉字),权重[1-11]或者100,如:“便宜云服务器租用|5” 或“ASR|11”; - 临时热词表限制:多个热词用英文逗号分割,最多支持128个热词,如:“便宜云服务器租用|10,语音识别|5,ASR|11”; - 参数 hotword_id(热词表) 与 hotword_list(临时热词表) 区别: - hotword_id:热词表。需要先在控制台或接口创建热词表,获得对应hotword_id传入参数来使用热词功能; - hotword_list:临时热词表。每次请求时直接传入临时热词表来使用热词功能,云端不保留临时热词表。适用于有极大量热词需求的用户; 注意: - 如果同时传入了 hotword_id 和 hotword_list,会优先使用 hotword_list; - 热词权重设置为11时,当前热词将升级为超级热词,建议仅将重要且必须生效的热词设置到11,设置过多权重为11的热词将影响整体字准率。 - 热词权重设置为100时,当前热词开启热词增强同音替换功能(仅支持8k_zh,16k_zh),举例:热词配置“蜜制|100”时,与“蜜制”同拼音(mizhi)的“秘制”的识别结果会被强制替换成“蜜制”。因此建议客户根据自己的实际情况开启该功能。建议仅将重要且必须生效的热词设置到100,设置过多权重为100的热词将影响整体字准率。 |
KeyWordLibIdList.N | 否 | Array of String | 关键词识别ID列表,默认空为不进行识别,最多10个 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
Data | Task | 录音文件识别的请求返回结果,包含结果查询需要的TaskId。 注意:TaskId有效期为24小时,不同日期可能出现重复TaskId,请不要依赖TaskId作为您业务系统里的唯一ID。 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 通过音频Url来调用接口
用户通过音频Url的方式(SourceType为0)请求录音识别服务,请求模型为16k中文 (EngineModelType = 16k_zh),音频格式为wav(采样率为16k,单声道)
输入示例
POST / HTTP/1.1
Host: asr.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Version: 2019-06-14
X-TC-Region: ap-shanghai
X-TC-Action: CreateRecTask
X-TC-Timestamp: 1599142560
Authorization: TC3-HMAC-SHA256 Credential=AKIDYu6A16GdCxUlnbTSVItxvhOr6B2xxxxx/2020-09-03/asr/tc3_request, SignedHeaders=content-type;host, Signature=524ed61a4a71de417f4fa41249dcb428a0c51013890f24f3492068ca7cd16953
<公共请求参数>
{
"Url": "http://test.cos.ap-guangzhou.myqcloud.com/test.wav",
"ChannelNum": 1,
"EngineModelType": "16k_zh",
"ResTextFormat": 0,
"SourceType": 0
}
输出示例
{
"Response": {
"RequestId": "3c140219-cfe9-470e-b241-907877d6fb03",
"Data": {
"TaskId": 1393265
}
}
}
示例2 通过音频数据来调用接口
用户通过上传音频数据(Data)的方式(SourceType为1)请求录音识别服务,请求模型为16k中文 (EngineModelType = 16k_zh),音频格式为wav(采样率为16k,单声道)
输入示例
POST / HTTP/1.1
Host: asr.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Version: 2019-06-14
X-TC-Region: ap-shanghai
X-TC-Action: CreateRecTask
X-TC-Timestamp: 1599142560
Authorization: TC3-HMAC-SHA256 Credential=AKIDYu6A16GdCxUlnbTSVItxvhOr6B2xxxxx/2020-09-03/asr/tc3_request, SignedHeaders=content-type;host, Signature=524ed61a4a71de417f4fa41249dcb428a0c51013890f24f3492068ca7cd16953
<公共请求参数>
{
"ChannelNum": 1,
"EngineModelType": "16k_zh",
"ResTextFormat": 0,
"Data": "eGNmYXNkZmFzZmFzZGZhc2RmCg==",
"SourceType": 1
}
输出示例
{
"Response": {
"RequestId": "3c140219-cfe9-470e-b241-907877d6fb03",
"Data": {
"TaskId": 1396665
}
}
}
5. 开发者资源
便宜云服务器租用 API 平台
便宜云服务器租用 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用便宜云服务器租用提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
AuthFailure.InvalidAuthorization | 鉴权错误。 |
FailedOperation.CheckAuthInfoFailed | 鉴权错误。 |
FailedOperation.ErrorDownFile | 下载音频文件失败。 |
FailedOperation.ErrorRecognize | 识别失败。 |
FailedOperation.ServiceIsolate | 账号因为欠费停止服务,请在便宜云服务器租用账户充值。 |
FailedOperation.UserHasNoAmount | 资源包耗尽,请购买资源包或开通后付费 |
FailedOperation.UserHasNoFreeAmount | 资源包耗尽,请开通后付费或者购买资源包 |
FailedOperation.UserNotRegistered | 服务未开通,请在便宜云服务器租用官网语音识别控制台开通服务。 |
InternalError.ErrorDownFile | 下载音频文件失败。 |
InternalError.FailAccessDatabase | 访问数据库失败。 |
InternalError.FailAccessRedis | 访问Redis失败。 |
InvalidParameter | 参数错误。 |
InvalidParameterValue | 参数取值错误。 |
MissingParameter | 缺少参数错误。 |
RequestLimitExceeded.UinLimitExceeded | 超出请求频率。 |
UnknownParameter | 未知参数错误。 |