跳到主要内容

ASR录音文件识别接口

目录​

使用要求​

项目说明
请求方式POST
响应格式以文本格式返回JSON数据
音频格式单通道或双通道的PCM、WAV、OPUS、MP3、MP4、M4A、WMA、AAC、OGG、AMR、FLAC、SPEEX、AC3、APE、M4R格式
采用PCM格式时,音频需满足采样率16k、位长16bit、单声道
音频大小音频不超过512MB，视频不超过2GB
音频时长不超过5小时
转写结果保存时长已完成结果保留72小时
转写结果获取次数转写完成后可获取不超过100次
最大转写时间最长不超过4小时

服务地址与鉴权方式​

服务地址​

所有API接口均基于以下基础URL：

https://aibook-api.mthreads.com:62220/api/v1/asr

鉴权方式​

本服务采用 Bearer Token 认证方式。在每次API请求时，需要在HTTP请求头中添加 Authorization 字段：

HTTP Header 格式:

Authorization: Bearer {your_access_token}

Python示例:

import requests

# 您的访问令牌
access_token = "your_access_token_here"

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://aibook-api.mthreads.com:62220/api/v1/asr/submit",
    headers=headers,
    json=request_data
)

注意: 访问令牌（Access Token）请联系我们获取。联系方式： meng.cai@mthreads.com, ye.wang@mthreads.com

HTTP POST​

交互流程​

使用音频URL时​

ASR文件识别URL

交互流程说明

阶段1：提交识别任务

客户端向服务端发送提交识别任务（Submit）的请求，并指定音频的URL；服务端收到请求后，会进行鉴权并初始化资源，并向客户端返回task_id。

当客户端在提交识别任务时设置了callback URL，服务端在完成识别后，会通过POST方式将识别结果发送到指定的URL。

阶段2：获取识别结果

客户端使用提交任务时得到的task_id，循环发送查询结果（Query）。服务端在未识别完成时会返回当前状态，在识别完成后会返回识别结果。

上传音频时​

ASR文件识别Upload

交互流程说明

阶段1：提交识别任务

客户端向服务端发送提交识别任务（Submit）的请求；服务端收到请求后，会进行鉴权并初始化资源，并向客户端返回task_id。

客户端向服务端上传音频（Upload）。当音频较大时，客户端可分块上传音频。客户端在分块上传过程中，每次应等待服务端告知当前数据块上传成功后，再接着上传下一块数据。

当客户端上传数据完成后，向服务端发送结束上传（UploadDone）的请求，服务端开始识别。

当客户端在提交识别任务时设置了callback URL，服务端在完成识别后，会通过POST方式将识别结果发送到指定的URL。

阶段2：获取识别结果

客户端使用提交任务时得到的task_id，循环发送查询结果（Query）。服务端在未识别完成时会返回当前状态，在识别完成后会返回识别结果。

提交识别任务​

请求​

在HTTP Body中使用JSON格式字符串。相关参数如下：

参数名类型必填说明
domainString否识别领域。目前仅支持general。
默认为general（通用场景）
languageString否语种。目前仅支持cn
默认为cn（中文）
audio_typeString否转写音频上传方式，默认为url
- url：使用网络链接
- upload：使用文件上传
当使用文件上传时，客户端需要在提交识别任务的xxx时间内，开始上传音频，否则识别超时
urlString是存放录音文件的url地址
仅当audio_type=url时生效
formatString否音频编码格式，默认是WAV
可选：PCM、WAV、OPUS、MP3、MP4、M4A、WMA、AAC、OGG、AMR、FLAC、SPEEX、AC3、APE、M4R
采用PCM格式时，仅支持采样率16k、位长16bit、单声道；其他格式支持单通道或双通道音频
lm_idString否自定义语言模型对应的ID，默认不添加
vocabulary_idString否自定义热词对应的ID，默认不添加
enable_punctuationBoolean否是否在后处理中添加标点，默认是False
enable_itnBoolean否逆文本归一化，即将识别结果中的中文数字转换阿拉伯数字。默认是False
remove_disfluencyBoolean否语气词过滤，即结果顺滑，默认是False
enable_speaker_infoBoolean否是否开启说话人分离功能，默认是False
show_confidenceBoolean否是否输出置信度，默认为False
show_wordsBoolean否是否开启返回词信息，默认为False
enable_semantic_sentence_detectionBoolean否是否开启语义断句，默认是False
max_single_segment_timeInteger否单句话允许的最长时间，单位为毫秒，默认是60000
max_sentence_lengthInteger否每句话的最大字数，默认为-1，表示不启用该功能
min_paragraph_lengthInteger否分段的最少字数，默认为-1，表示不启用该功能
max_paragraph_lengthInteger否分段的最大字数，默认为-1，表示不启用该功能
special_word_filterString (文本化的JSON字符串)否敏感词过滤功能，可根据实际需求开启或关闭自定义词或默认词表。默认为空字符串，该参数支持：
- 空字符串：不处理
- 字典Dict：敏感词替换
- 列表List：敏感词替换为*
callbackString否回调服务的地址，默认为空
当callback非空时，在识别完成后，会使用将结果POST到该URL。要求URL支持HTTP和HTTPS协议，host不可使用IP地址
enable_queryBoolean否该参数仅在callback非空时有效
如果使用回调功能并且设置enable_query=False，当服务端识别完成并调用callback后，不能再使用query接口查询结果。默认为False
若该参数设置为True，则在回调后依然允许使用query查询结果
first_channel_onlyBoolean否是否只识别首个声道，默认为False
channel_splitBoolean否该参数仅在first_channel_only=False时有效
当识别所有声道的内容时，是否要分轨识别。分轨识别是指，分别识别不同声道的内容。默认为False，表示将所有声道混合在一起识别。
如果为True，则会分别识别各个声道，并在结果中使用channel_id表示来源。例如，对于一条双通道音频，当channel_split=True时，将会分别识别左右声道的内容。
valid_timesList否有效时间段信息，用来排除一些不需要的时间段。
其中，valid_time参数中的每个元素说明如下：
- start_time (Integer, 必填)：音频段起始时间，单位为毫秒
- end_time (Integer, 必填)：音频段结束时间，单位为毫秒
- channel_id (Integer, 可选)：音频所属声道，默认为0

示例​

{
  "appid":"76e81efb964447",
  "domain":"general",
  "language":"cn",
  "audio_type":"url",
  "url":"https://oss.mthreads.com/test.wav",
  "format":"wav",
  "lm_id":0,
  "vocabulary_id":0,
  "enable_punctuation":true,
  "enable_itn":true,
  "remove_disfluency":true,
  "enable_speaker_info":false,
  "enable_timestamp_alignment":false,
  "show_confidence":true,
  "show_words":true,
  "max_end_silence":800,
  "enable_semantic_sentence_detection":true,
  "max_single_segment_time":60000,
  "max_sentence_length":-1,
  "min_paragraph_length":-1,
  "special_word_filter":"",
  "callback":"https://callback.mthreads.com",
  "enable_query":true,
  "first_channel_only":false,
  "channel_split":true,
  "valid_times":[
    {
      "channel_id":0,
      "start_time":0,
      "end_time":60000
    }
  ]
}

响应​

返回HTTP状态码为200时，表示成功；其余为失败

字段类型说明
task_idString任务id
statusInteger识别状态码
status_textString状态说明

如果设置了callback，在识别结束后，服务端会向指定的URL发送HTTP POST请求。具体请求内容请参考"查询结果"部分。

示例

{
  "task_id":"4c0d4443fcd34567b42e028a54400e40",
  "status":1000,
  "status_text":"Success."
}

上传音频​

请求​

仅在提交任务时指定audio_type=upload时，能使用上传音频功能。当音频文件过大时，可以每次上传一部分数据，分多次上传。

进行分块时，建议用户一次性上传不超过10M的数据。

在进行音频上传时，相关参数放在HTTPS请求行中，二进制数据放在请求体中。

HTTPS请求行

参数名类型必填说明
task_idString是在"提交识别任务"阶段，服务端返回的task_id

HTTPS请求头

参数名类型必填说明
Content-TypeString是取值"application/octet-stream"，表明HTTPS请求体的数据为二进制流。

HTTPS请求体

待识别音频的二进制数据

示例

POST http://url/upload?task_id=68753A444D6F12269C600050E4C00067 HTTP/1.1
Content-Type: application/octet-stream;
content of audio[语音文件的二进制数据]

响应​

字段类型说明
statusInteger识别状态码
status_textString状态说明

示例

{
  "task_id":"4c0d4443fcd34567b42e028a54400e40",
  "status":1000,
  "status_text":"Success."
}

结束上传​

请求​

在完成所有音频片段的上传后，需要发送"结束上传"的请求。发送"结束上传"后，该音频进入服务端处理队列。请求参数说明：

参数名类型必填说明
task_idString是在"提交识别任务"阶段，服务端返回的task_id
md5String是上传文件的MD5码值，用于文件完整性校验。

示例

{
  "task_id":"4c0d4443fcd34567b42e028a54400e40",
  "md5":"cc57b89407609632014997eeb90f0c86"
}

响应​

字段类型说明
statusInteger识别状态码
status_textString状态说明

示例

{
  "status":1000,
  "status_text":"Success."
}

查询结果​

请求​

请求体为空

响应​

字段类型说明
task_idString任务id
statusInteger识别状态码
除"成功"、不同的识别失败外，还包括：
- 排队中
- 识别中
status_textString状态说明
durationLong识别音频总时长，单位是毫秒
仅在开始识别后显示
finished_timeInteger已完成转写的音频时长，单位是毫秒
仅在开始识别后显示
cost_timeInteger开始转写后的耗时，单位是毫秒
仅在识别完成后返回
textString识别结果
仅在识别完成后返回
sentencesList句子级别识别结果
仅在识别完成后返回

句子级别结果sentences中的字段说明：

字段类型说明
channelInteger该句对应的音轨ID
start_timeInteger该句的起始时间
end_timeInteger该句的结束时间
textString该句的识别结果
speakerInteger该句对应的说话人ID
confidenceDouble当前句子识别结果的置信度，取值范围：[0.0,1.0]。值越大表示置信度越高。
仅在show_confidence=True时显示
wordsList该句对应的词级别信息
仅在show_words=True时显示

词级别信息words中的字段说明

字段类型说明
textString词的文本
start_timeInteger词的起始时间，单位毫秒
end_timeInteger词的结束时间，单位毫秒

示例​

排队中：

{
  "task_id":"4c0d4443fcd34567b42e028a54400e40",
  "status":3000,
  "status_text":"Queueing."
}

识别中：

{
  "task_id":"4c0d4443fcd34567b42e028a54400e40",
  "status":2000,
  "status_text":"Processing.",
  "duration":60000,
  "finished_time":30000
}

识别完成：

{
  "taskid":"4c0d4443fcd34567b42e028a54400e40",
  "status":1000,
  "status_text":"Success.",
  "duration":60000,
  "finished_time":60000,
  "cost_time":5000,
  "text":"摩尔线程",
  "sentences":[
    {
      "channel":0,
      "start_time":0,
      "end_time":1500,
      "text":"摩尔线程",
      "speaker":0,
      "confidence":0,
      "words":[
        {
          "text":"摩",
          "start_time":430,
          "end_time":870
        },
        {
          "text":"尔",
          "start_time":870,
          "end_time":990
        },
        {
          "text":"线",
          "start_time":990,
          "end_time":1140
        },
        {
          "text":"程",
          "start_time":1140,
          "end_time":1430
        }
      ]
    }
  ]
}

状态码​

状态码状态消息说明
1000success!成功
1001waiting排队中
1002running识别中
2001appid doesn't exist!appid不存在
2002authorization failed.鉴权失败
2003too many requests并发数量过多
2004service overload数据发送过快,服务超负荷
3001service is busy服务器忙
3002service timeout服务处理超时
3003client is disconnected未完成前客户端主动断开
3004errors occured during processing识别过程中发生错误
3005cannot find the taskid任务过期,或taskid不存在
3006invalid audio typeaudio type非法
3007language is not supported输入的语种不支持
3008target language is not supported翻译目标语种不支持
3009errors occured during translation翻译过程中发生错误
4001unknown parameter is given.输入了未知/不支持的参数
4002given value is invalid参数值非法
4003request invalid请求消息格式错误
4004fail to read the audio音频解码失败
4005unsupported audio format音频格式不支持
4006audio too large音频文件过大
4007audio too long音频时长过长
4008fail to download the audio file文件下载失败
4009data timeout发送数据超时,等待下一包太久,导致识别结束
4010url is invalidURL非法
4011callback url is invalidcallback URL非法
4012fail to check content-lengthcontent-length 检查失败
4013fail to check md5音频md5校验失败
4014fail to upload audio data文件上传失败或超时
4015duplicated upload done detected重复发送UploadDone
4016duplicated start detected未按照规定的交互流程发送请求

示例代码​

请参考: https://github.com/yiliu-mt/mtasr_examples/blob/main/recording_recognition/python/recording_recognition.py

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。