接口说明

最近更新时间:2019-09-04 18:55:02

接口描述

本接口服务对一小时之内的录音文件进行识别,异步返回全部识别结果。

  • 支持语音 URL 和本地语音文件上传两种请求方式
  • 支持话者分离的功能

接口要求

使用录音文件识别 SDK 时,需按照以下要求。

内容 说明
音频属性 采样率16k或8k、采样精度16bits、单声道或双声道,查看音频属性请参见 常见问题
音频格式 支持 wav、pcm、mp3、silk、speex、amr、m4a等主流音频格式
数据长度 若采用直接上传音频数据方式,建议音频数据不能大于5MB
若采用上传音频 URL 方式,建议音频时长不能大于1小时
调用方式 目前仅支持回调
免费额度 每月30小时

使用步骤

  1. 首先获取您的 AppID、SecretID 和 SecretKey。在使用该接口前,需要在 语音识别控制台 开通服务,并进入 API 密钥管理页面 新建密钥,生成 AppID、SecretID 和 SecretKey ,用于 SDK 调用时生成签名,签名将用来进行接口鉴权。
  2. 查看您的音频属性和格式,应满足接口支持的属性和格式,否则会请求失败。
  3. 通过 SDK 提交录音文件识别的请求,正常情况下服务器端会返回该请求的状态。
  4. 如果返回的 code = 0,表示请求成功,当语音识别系统完成识别后,会将结果通过 HTTP POST 请求的形式通知到用户,用户需要在自身业务服务器上搭建服务接收回调;如果返回的 code 不为0,请参见 错误码 详情。

录音文件识别请求

结果调用方式目前仅支持回调,需要客户端在提交语音识别请求时提交回调 URL,识别完成后服务端会把识别结果通过 HTTP POST 形式发给回调 URL。

请求参数

请求参数主要由请求 URL请求头部组成。

请求 URL 示例

https://aai.qcloud.com/asr/v1/125000001?engine_model_type=0
&expired=1473752807
&nonce=44925
&projectid=0
&res_text_format=0
&res_type=1
&secretid=<secretid>
&source_type=0
&sub_service_type=0
&timestamp=1473752207
&url=<url>
&callback_url=<callback_url>

请求 URL 参数说明

参数名称 必选 类型 描述
AppId Int 用户在腾讯云注册账号的 AppId,可以进入 API密钥管理页面 获取
projectid Int 腾讯云项目 ID,语音识别目前不区分项目,所以填0即可。
secretid String 用户在腾讯云注册账号 AppId 对应的 SecretId,可以进入 API 密钥管理页面 获取
sub_service_type Int 子服务类型。0:录音文件识别
engine_model_type String 引擎类型。8k_0:电话 8k 通用模型;16k_0:16k 通用模型;8k_6: 电话场景下单声道话者分离模型
res_text_format Int 识别结果文本编码方式。0:UTF-8;1:GB2312;2:GBK;3:BIG5
callback_url String 回调 URL,用户自行搭建的用于接收识别结果的服务器地址, 长度小于2048字节
channel_num Int 语音声道数,1:单声道;2:双声道(仅在电话 8k 通用模型下支持)
source_type Int 语音数据来源。0:语音 URL;1:语音数据(post body)
url String 语音的 URL 地址,需要公网可下载。长度小于2048字节,当 source_type 值为0时须填写该字段,为 1 时不需要填写
timestamp Int 当前 UNIX 时间戳,可记录发起 API 请求的时间。如果与当前时间相差过大,会引起签名过期错误。可以取值为当前请求的系统时间戳即可
expired Int 签名的有效期,是一个符合 UNIX Epoch 时间戳规范的数值,单位为秒;Expired 必须大于 Timestamp 且 Expired - Timestamp 小于90天。
nonce Int 随机正整数。用户需自行生成,最长10位。

请求头部示例

{
"Content-Type":"application/octet-stream",
"Authorization":"UyKZ+Q4xMbdu3gxOmPD7tgnAm1A="
}

请求头部参数说明

参数名称 必选 类型 描述
Host String 语音识别服务域名,固定为 aai.qcloud.com
Authorization String 用户的有效签名,用于鉴权
Content-Type String application/octet-stream
Content-Length Int 请求长度,此处对应语音数据字节数,单位:字节

返回参数

当服务端收到录音识别请求后,会返回该请求的状态。
请求返回示例
请求成功会返回如下状态:

 { "code":0, "message":"success", "requestId":500 }

返回参数说明

参数名称 类型 描述
code Int 服务器错误码,0为成功
message String 服务器返回的信息
requestId Int 如果成功,返回任务 ID

录音文件识别结果查询

结果调用方式目前仅支持回调,需要客户端在提交语音识别请求时提交回调 URL,识别完成后服务端会把识别结果通过 HTTP POST 形式发给回调 URL。

识别结果回调

服务端结果返回示例

code=0&requestId=500&appid=12000001&projectid=0&text=%e6%82%a8%e5%a5%bd&audioUrl=http%3a%2f%2ftest.qq.com%2fvoice_url&audioTime=2.5&message=success
注意:

为了防止某些字段中,出现诸如 “&” 等特殊字符,导致解包失败,所有字段的 value 值都将进行 url_encode 之后发送给用户业务服务器,在获取 value 之后,需要先对 value 进行 url_decode 以获取原始 value 值。

服务端返回参数说明

字段 类型 描述
code Int 服务器错误码,0 为成功,其他:失败
message String 成功或者失败原因文字描述
requestId Int 请求 ID,与后台任务 ID 一一对应
AppId Int 腾讯云应用 ID
projectid Int 腾讯云项目 ID
audioUrl String 语音下载 URL。如果语音源非公网可下载 URL,则不包含该字段
text String 识别出的结果文本
audioTime Double 语音总时长

客户端确认

客户端确认示例
语音识别系统发起请求,收到请求后,用户侧需要以 JSON 格式回以响应

{ "code" : 0, "message" : "成功" }

客户端确认参数说明

参数名称 类型 描述
code Int 错误码,0为成功,其他值代表失败
message String 失败原因说明,例如业务服务器过载。 如果业务服务器返回失败,会间隔一段时间重新通知

错误码

请求错误码

数值 返回码 说明
1000 ERROR_BAD_REQ 请求的参数不符合要求
1001 ERROR_PARSE_DATA_FAILED 解析请求参数时失败
1002 ERROR_HAS_NO_VALID_PROJECTID 没有提供 projectid,或者值不合法
1003 ERROR_HAS_NO_VALID_RES_TEXT_FORMAT 没有提供 res_text_format,或者值不合法
1004 ERROR_HAS_NO_VALID_SUB_SERVICE_TYPE 没有提供 sub_service_type,或者值不合法
1005 ERROR_HAS_NO_VALID_ENGINE_MODEL_TYPE 没有提供 engine_model_type,或者值不合法
1006 ERROR_HAS_NO_VALID_CALLBACK_URL 没有提供 callback_url,或者值不合法
1007 ERROR_HAS_NO_VALID_RES_TYPE 没有提供 res_type,或者值不合法
1008 ERROR_HAS_NO_VALID_SOURCE_TYPE 没有提供 source_type,或者值不合法
1009 ERROR_HAS_NO_VALID_URL 没有提供下载语音的 URL,或者值不合法
1010 ERROR_HAS_NO_VALID_SECRET_ID 没有提供 SecretId,或者值不合法
1011 ERROR_HAS_NO_VALID_TIMESTAMP 没有提供 timestamp,或者值不合法
1012 ERROR_HAS_NO_VALID_EXPIRED 没有提供 expired,或者值不合法
1013 ERROR_HAS_NO_VALID_NONCE 没有提供 nonce,或者值不合法
1014 ERROR_HAS_NO_VALID_TEMPLATENAME 提供的 template_name 不合法
1015 ERROR_HAS_NO_BUCKET 没有提供 bucket,或者值不合法
1016 ERROR_HAS_NO_AMOUNT 没有剩余的免费用量
1017 ERROR_URL_TOO_LONG 提供的 URL 长度大于2048字符
1018 ERROR_FILEID_TOO_LONG 提供的文件名长度大于2048字符
1019 ERROR_APPID_NOT_REGISTER 提供的 AppID 未注册
1020 ERROR_APPID_PROJECTID_TEMPLATENAME_MISMATCH 提供的 AppID,ProjectId 与 template_name 不匹配
1021 ERROR_PROCESS_FAILED 服务端处理出现内部错误
1022 ERROR_PROXY_BAD_AUTH 签名不符合规则
1024 ERROR_PROXY_AUTH_TOO_LONG_EXPIRED 签名的有效期设置太长
1025 ERROR_PROXY_AUTH_EXPIRED 签名过期
1026 ERROR_PROXY_AUTH_PROJECTID_NOEXIST 签名中的 ProjectId 错误
1027 ERROR_PROXY_AUTH_SECRETID_NOEXIST 签名中的 SecretId 错误
1028 ERROR_PROXY_AUTH_PROJECTID_MISMATCH 签名中的 ProjectId 不匹配
1029 ERROR_PROXY_AUTH_REPLAY_ATTACK 重放攻击
1030 ERROR_PROXY_AUTH_FAILED 签名验证不通过
1032 ERROR_AUDIO_TOO_LARGE 发送的语音数据过大(大于5MB)
1034 ERROR_UNKNOWN 其他未知错误

回调错误码

数值 说明
10000 语音非标准格式,转码失败
10001 识别不成功
10002 语音时长过长
10003 语音时长过长
10004 无效的语音文件
10005 其他失败
10006 音轨个数不匹配