全部产品

接口说明

更新时间:2019-08-09 23:20:04

功能介绍

录音文件识别是针对已经录制完成的录音文件,进行识别的服务。录音文件识别是非实时的,识别的文件需要提交基于HTTP可访问的URL地址,不支持提交本地文件。

  • 支持单轨/双轨的wav格式、mp3格式的录音文件识别;
  • 支持两种调用方式:轮询方式和回调方式;
  • 支持自学习平台和热词;
  • 支持8000Hz、16000Hz的采样率;
  • 支持汉语普通话、方言、欧美英语等多种模型识别;

调用限制

使用步骤

  1. 了解您的录音文件格式和采样率,根据您的业务场景在管控台中选择合适的场景和模型
  2. 把录音文件存放到OSS。如果文件访问权限为公开,可以直接获取文件访问链接;如果文件访问权限为私有,可以通过SDK生成有过期时间的访问链接。(您也可以搭建自己的文件服务器,并且把录音文件存放到您自己的服务器上,自行搭建文件服务器提供文件下载,请保证HTTP的响应头(Header)中的Content-Length的长度值 和Body中的数据的真实长度一致,否则会导致下载失败。)
  3. 客户端提交录音文件识别请求,正常服务端会返回该请求任务的ID,用以查询识别结果。
  4. 客户端发送识别结果查询请求,通过步骤3获取的请求任务ID查询录音文件识别的结果,目前识别的结果在服务端可保存72小时。

客户端与服务端的交互流程如图所示:

交互流程

说明: 所有服务端的响应都会在返回信息的header包含TaskId参数,用于表示本次识别任务的ID,请记录下这个值,如果发生错误,请将task_id和错误信息提交到工单。

接口调用方式

录音文件识别服务是以RPC风格的POP API方式提供录音文件识别接口,将参数封装到每一个请求中,每个请求即对应一个方法,执行的结果放在response中。需要识别的录音文件必须存放在某服务上(推荐阿里云OSS),可以通过URL访问。

录音文件识别POP API包括两部分:POST方式的“录音文件识别请求调用接口”,GET方式的“录音文件识别结果查询接口”。

录音文件识别请求调用接口

  • 当采用轮询方式时,提交录音文件识别任务,获取任务ID,供后续轮询使用。
  • 当采用回调方式时,提交录音文件识别任务和回调URL,任务完成后会把识别结果POST到回调地址,需要回调地址可接收POST请求。

历史版本说明:由于历史原因,早期发布的录音文件识别服务(默认为2.0版本)的回调方式和轮询方式的识别结果在JSON字符串的风格和字段上均有不同,下文将作说明。录音文件识别服务在4.0版本对回调方式做了更新,使得回调方式的识别结果与轮询方式的识别结果保持一致,均为驼峰风格的JSON格式字符串。如果您已接入录音文件识别服务,即没有设置录音文件识别服务的版本,默认为2.0版,可以继续使用;如果您是新接入录音文件识别服务,请设置服务版本为4.0。

输入参数

提交录音文件识别请求时,需要设置输入参数,以JSON格式的字符串传入请求对象的Body,JSON格式例如:

  1. {
  2. "appkey": "your-appkey",
  3. "file_link": "https://aliyun-nls.oss-cn-hangzhou.aliyuncs.com/asr/fileASR/examples/nls-sample-16k.wav",
  4. "auto_split":false,
  5. "version": "4.0",
  6. "enable_words": false,
  7. // valid_times是获取语音的指定时间段的识别内容,如果不需要,则不用填写
  8. "valid_times": [
  9. {
  10. "begin_time": 200,
  11. "end_time":2000,
  12. "channel_id": 0
  13. }
  14. ]
  15. }

输入参数解析:

属性 值类型 是否必须 说明
appkey String 在管控台中创建的项目Appkey,项目的唯一标识
file_link String 存放录音文件的地址链接,需要在管控台中将对应项目的模型设置为支持该音频场景的模型
version String 设置录音文件识别服务的版本,请设置为”4.0”,默认为”2.0”
enable_words Boolean 是否开启返回词信息,默认为false,开启时需要设置version为”4.0”
enable_callback Boolean 是否启用回调功能,默认值为false
callback_url String 回调服务的地址,enable_callback=true时,本字段必填,url支持HTTP和HTTPS协议,host不能使用IP地址
auto_split Boolean 是否开启智能分轨(开启智能分轨,即可在两方对话的语音情景下,依据每句话识别结果中的ChannelId,判断该句话的发言人为哪一方。通常先发言一方ChanelId为1。只支持8000Hz采样率单通道语音。)
valid_times List< ValidTime > 有效时间段信息,用来排除一些不必要的时间段

其中,ValidTime对象的参数描述:

属性 值类型 是否必须 说明
begin_time Int 有效时间段的起始点时间偏移(单位: ms)
end_time Int 有效时间段的结束点时间偏移(单位: ms)
channel_id Int 有效时间段的作用音轨序号(从0开始)

输出参数

服务端返回录音文件识别请求的响应,响应的输出参数为JSON格式的字符串:

  1. {
  2. "TaskId": "4b56f0c4b7e611e88f34c33c2a60497b",
  3. "RequestId": "E4B183CC-6CFE-411E-A547-D877F7BD6C44",
  4. "StatusText": "SUCCESS",
  5. "StatusCode": 21050000
  6. }

输出参数描述:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回参数JSON字符串:
属性 值类型 是否必须 说明
TaskId String 识别任务ID
RequestId String 请求ID,仅用于联调
StatusCode Int 状态码
StatusText String 状态说明

录音文件识别结果查询接口

在提交完录音文件识别请求后,您可以按照如下参数设置轮询识别结果。

输入参数

通过提交录音文件识别请求获得的任务ID作为识别结果查询接口参数,可以获取识别结果,在接口调用过程中,需要设置一定的查询时间间隔。

属性 值类型 是否必须 说明
TaskId String 识别任务ID

输出参数

服务端返回识别结果查询请求的响应,响应的输出参数为JSON格式的字符串。

正常返回:以录音文件 nls-sample-16k.wav(文件为单轨)识别结果为例:

  1. {
  2. "TaskId": "d429dd7dd75711e89305ab6170fe6cd1",
  3. "RequestId": "9240D669-6485-4DCC-896A-F8B31F946CF9",
  4. "StatusText": "SUCCESS",
  5. "BizDuration": 2956,
  6. "SolveTime": 1540363288472,
  7. "StatusCode": 21050000,
  8. "Result": {
  9. "Sentences": [{
  10. "EndTime": 2365,
  11. "SilenceDuration": 0,
  12. "BeginTime": 340,
  13. "Text": "北京的天气。",
  14. "ChannelId": 0,
  15. "SpeechRate": 177,
  16. "EmotionValue": 5.0
  17. }]
  18. }
  19. }

如果开启enable_callback/callback_url,且设置服务版本为4.0,回调识别结果为:

  1. {
  2. "Result": {
  3. "Sentences": [{
  4. "EndTime": 2365,
  5. "SilenceDuration": 0,
  6. "BeginTime": 340,
  7. "Text": "北京的天气。",
  8. "ChannelId": 0,
  9. "SpeechRate": 177,
  10. "EmotionValue": 5.0
  11. }]
  12. },
  13. "TaskId": "36d01b244ad811e9952db7bb7ed2b0dd",
  14. "StatusCode": 21050000,
  15. "StatusText": "SUCCESS",
  16. "RequestTime": 1553062810452,
  17. "SolveTime": 1553062810831,
  18. "BizDuration": 2956
  19. }

说明:

  • RequestTime为时间戳(单位为毫秒,例如1553062810452为转换为北京时间为2019/3/20 14:20:10),表示录音文件识别提交请求的时间。
  • SolveTime为时间戳(单位为毫秒),表示录音文件识别完成的时间。

排队中:

  1. {
  2. "TaskId": "c7274235b7e611e88f34c33c2a60497b",
  3. "RequestId": "981AD922-0655-46B0-8C6A-5C836822F773",
  4. "StatusText": "QUEUEING",
  5. "StatusCode": 21050002
  6. }

识别中:

  1. {
  2. "TaskId": "c7274235b7e611e88f34c33c2a60497b",
  3. "RequestId": "8E908ED2-867F-457E-82BF-4756194A6C78",
  4. "StatusText": "RUNNING",
  5. "BizDuration": 0,
  6. "StatusCode": 21050001
  7. }

异常返回:

以文件下载失败为例:

  1. {
  2. "TaskId": "4cf25b7eb7e711e88f34c33c2a60497b",
  3. "RequestId": "098BF27C-4CBA-45FF-BD11-3F532F261733",
  4. "StatusText": "FILE_DOWNLOAD_FAILED",
  5. "BizDuration": 0,
  6. "SolveTime": 1536906469146,
  7. "StatusCode": 41050002
  8. }

更多异常情况请查看下面的服务状态码的错误状态码及解决方案。

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON字符串
属性 值类型 是否必须 说明
TaskId String 识别任务ID
StatusCode Int 状态码
StatuxText String 状态说明
RequestId String 请求id,用于调试
Result Object 识别结果对象
Sentences List< SentenceResult > 识别的结果数据。当StatuxText为SUCCEED时存在
Words List< WordResult > 词信息,获取时需设置enable_words为true,且设置服务version为”4.0”
BizDuration Long 识别的音频文件总时长,单位为毫秒
SolveTime Long 时间戳,单位为毫秒,录音文件识别完成的时间

其中,单句结果SentenceResult描述:

属性 值类型 是否必须 说明
ChannelId Int 该句所属音轨ID
BeginTime Int 该句的起始时间偏移,单位为毫秒
EndTime Int 该句的结束时间偏移,单位为毫秒
Text String 该句的识别文本结果
EmotionValue Int 情绪能量值1-10,值越高情绪越强烈
SilenceDuration Int 本句与上一句之间的静音时长,单位为秒
SpeechRate Int 本句的平均语速,单位为每分钟字数

开启返回词信息:如果enable_words设置为true,且设置服务version为”4.0”,服务端的识别结果将包含词信息。使用轮询方式和回调方式,获得的词信息相同,以轮询方式的识别结果为例:

  1. {
  2. "StatusCode": 21050000,
  3. "Result": {
  4. "Sentences": [{
  5. "SilenceDuration": 0,
  6. "EmotionValue": 5.0,
  7. "ChannelId": 0,
  8. "Text": "北京的天气。",
  9. "BeginTime": 340,
  10. "EndTime": 2365,
  11. "SpeechRate": 177
  12. }],
  13. "Words": [{
  14. "ChannelId": 0,
  15. "Word": "北京",
  16. "BeginTime": 640,
  17. "EndTime": 940
  18. }, {
  19. "ChannelId": 0,
  20. "Word": "的",
  21. "BeginTime": 940,
  22. "EndTime": 1120
  23. }, {
  24. "ChannelId": 0,
  25. "Word": "天气",
  26. "BeginTime": 1120,
  27. "EndTime": 2020
  28. }]
  29. },
  30. "SolveTime": 1553236968873,
  31. "StatusText": "SUCCESS",
  32. "RequestId": "027B126B-4AC8-4C98-9FEC-A031158F3F5A",
  33. "TaskId": "b505e78c4c6d11e9a213e11db149f2ff",
  34. "BizDuration": 2956
  35. }

Word对象说明:

属性 值类型 是否必须 说明
BeginTime Int 词开始时间,单位毫秒
EndTime Int 词结束时间,单位毫秒
ChannelId Int 该词所属音轨ID
Word String 词信息

服务状态码

正常状态码:

状态码 状态描述 状态含义 解决方案
21050000 SUCCESS 成功 POST方式的识别请求接口调用成功,或者GET方式的识别结果查询接口调用成功
21050001 RUNNING 录音文件识别任务运行中 请稍后再发送GET方式的识别结果查询请求
21050002 QUEUEING 录音文件识别任务排队中 请稍后再发送GET方式的识别结果查询请求
21050003 SUCCESS_WITH_NO_VALID_FRAGMENT 识别结果查询接口调用成功,但是没有识别到语音 检查录音文件是否有语音,或者语音时长太短

错误状态码:

说明:状态码4开头表示客户端错误,5开头表示服务端错误。

状态码 状态描述 状态含义 解决方案
41050001 USER_BIZDURATION_QUOTA_EXCEED 单日时间超限 如业务量较大,请联系商务洽谈 邮件地址:nls_support@service.aliyun.com
41050002 FILE_DOWNLOAD_FAILED 文件下载失败 检查录音文件路径是否正确,是否可以外网访问和下载
41050003 FILE_CHECK_FAILED 文件格式错误 检查录音文件是否是单轨/双轨的WAV格式、MP3格式
41050004 FILE_TOO_LARGE 文件过大 检查录音文件大小是否超过512MB
41050005 FILE_NORMALIZE_FAILED 文件归一化失败 检查录音文件是否有损坏,是否可以正常播放
41050006 FILE_PARSE_FAILED 文件解析失败 检查录音文件是否有损坏,是否可以正常播放
41050007 MKV_PARSE_FAILED MKV解析失败 检查录音文件是否有损坏,是否可以正常播放
41050008 UNSUPPORTED_SAMPLE_RATE 采样率不支持 检查录音文件采样率是否是8000、16000
41050009 UNSUPPORTED_ASR_GROUP ASR分组不支持 确认下ak和appkey是否一致
41050010 FILE_TRANS_TASK_EXPIRED 录音文件识别任务过期 TaskId不存在,或者已过期
41050011 REQUEST_INVALID_FILE_URL_VALUE 请求file_link参数非法 请确认file_link参数格式是否正确
41050012 REQUEST_INVALID_CALLBACK_VALUE 请求callback_url参数非法 请确认callback_url参数格式是否正确,是否为空
41050013 REQUEST_PARAMETER_INVALID 请求参数无效 确认下请求task值为有效JSON格式字符串
41050014 REQUEST_EMPTY_APPKEY_VALUE 请求参数appkey值为空 请确认是否设置了appkey参数值
41050015 REQUEST_APPKEY_UNREGISTERED 请求参数appkey未注册 请确认请求参数appkey值是否设置正确,或者是否与阿里云账号的AccessKey ID同一个账号
41050021 RAM_CHECK_FAILED RAM检查失败 请检查您的RAM用户是否已经授权调用语音服务的API,请阅读开通服务—RAM用户鉴权配置
41050023 CONTENT_LENGTH_CHECK_FAILED content-length 检查失败 请检查下载文件时,http response中的content-length与文件实际大小是否一致.
41050024 FILE_404_NOT_FOUND 需要下载的文件不存在 请检查需要下载的文件是否存在.
41050025 FILE_403_FORBIDDEN 没有权限下载需要的文件 请检查是否有权限下载录音文件.
41050026 FILE_SERVER_ERROR 请求的文件所在的服务不可用 请检查请求的文件所在的服务是否可用.
51050000 INTERNAL_ERROR 内部通用错误 如果偶现可以忽略,重复出现请提交工单
51050001 VAD_FAILED VAD失败 如果偶现可以忽略,重复出现请提交工单
51050002 RECOGNIZE_FAILED 内部alisr识别失败 如果偶现可以忽略,重复出现请提交工单
51050003 RECOGNIZE_INTERRUPT 内部alisr识别中断 如果偶现可以忽略,重复出现请提交工单
51050004 OFFER_INTERRUPT 内部写入队列中断 如果偶现可以忽略,重复出现请提交工单
51050005 FILE_TRANS_TIMEOUT 内部整体超时失败 如果偶现可以忽略,重复出现请提交工单
51050006 FRAGMENT_FAILED 内部分断失败 如果偶现可以忽略,重复出现请提交工单

历史版本说明

如果您已接入录音文件识别,即没有设置服务版本为4.0,您将默认使用的是录音文件识别2.0版本,使用回调方式的识别结果与轮询方式的识别结果在JSON字符串的风格和字段上有所不同,回调方式识别结果如下所示:如果开启enable_callback/callback_url,回调识别结果为:

  1. {
  2. "result": [{
  3. "begin_time": 340,
  4. "channel_id": 0,
  5. "emotion_value": 5.0,
  6. "end_time": 2365,
  7. "silence_duration": 0,
  8. "speech_rate": 177,
  9. "text": "北京的天气。"
  10. }],
  11. "task_id": "3f5d4c0c399511e98dc025f34473d12f",
  12. "status_code": 21050000,
  13. "status_text": "SUCCESS",
  14. "request_time": 1551164878830,
  15. "solve_time": 1551164879230,
  16. "biz_duration": 2956
  17. }