Server API

一 功能介绍

录音文件转写,是将已经录制好的音频文件, 通过识别服务,将长段音频数据(5小时以内)转写成文本数据,可用于采访录音转写、音频数据录入、会议记录总结等场景,支持:

  • 可用于基于协议开发的:轻量级嵌入式设备;采用云对云的方式,接入DUI实时语音转写服务的产品;
  • 支持pcm,wav,ogg(speex),ogg_opus,mp3,aac,m4a格式的音频文件转写;
  • 有效任务12个小时内出转写结果;
  • 对于大音频文件可以进行分片上传;(注意:如您已接入转写服务,且接入的服务接口不支持分片上传功能,那么您接入的是V1版本接口,详见:录音文件转写V1版本(Server))
  • 支持自定义热词和敏感词配置、语言模型自训练功能,请联系商务或项目经理进行定制。

 

整个识别过程是非实时的,音频文件上传成功后进入等待队列,转写成功后用户可以获取转写结果。返回转写结果时间受排队队列、音频时长因素影响,如转写耗时比平时长,耐心等待即可。

二 调用限制

集成录音文件长语音转写API时,需按照以下要求:

内容 说明
请求协议 http[s]
接口鉴权 详见:接口授权
字符编码 UTF-8
响应格式 统一采用JSON格式
开发语言 任意,只要可以向思必驰录音文件转写服务发起http请求即可
音频属性 采样率16k、位长16bits、单声道
音频时长/大小 5小时以内,且不超过500M
音频格式 pcm,wav,ogg(speex),ogg_opus,mp3,aac,m4a
语言种类 中文普通话,英文,中英混合,中川,中粤
并发路数 默认5路并发。
转写结果保存时长 最多保存7天

 

三 接入流程

3.1 流程说明

  1. 注册DUI账号并进行实名认证,点此进行注册:注册DUI账号;
  2. 在DUI控制台上创建基础技术产品,并完成产品授权;
  3. 完成长语音服务接口授权;
  4. 调用长语音接口,实现语音转写功能。

3.2 产品创建与授权

3.2.1 创建基础技术产品

集成录音文件长语音转写API,需要先创建基础技术服务产品。

  1. 登录DUI控制台后,点击导航栏的【基础技术】,进入基础技术产品列表页。
  2. 在列表页,点击【基础技术接入】,创建基础技术产品,选择接实时转写服务。
  3. 选择需要接入的录音文件转写服务。

 

3.2.2 产品授权

  1. 进入基础技术产品详情页, 点击【授权管理】,进入授权页。
  2. 在授权页,根据业务需求,选择授权方式。云端对云端的情况请选择 【服务授权】。
  3. 选择【配置IP白名单】,填写需要调用识别服务的IP地址,提交后,会生成授权所需的APIkey。请注意,IP地址为实际访问长语音服务的IP地址。

3.3 服务接口鉴权

详见:接口鉴权

四 接口调用

  • 创建音频

【地址】:/lasr-file-api/v2/audio?productId={PRODUCT_ID}&apiKey={APIKEY}

【Host】:lasr.duiopen.com

【请求】:

方式:POST

请求头:Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数:

参数

类型

必须

说明

audio_type String 是

音频文件的格式。

可选值:

pcm

wav

ogg_speex

ogg_opus

mp3

opus

sample_rate int 否

音频文件的采样率。

可选值: 16000(默认值), 8000

客户端没有传递sample_rate参数时,等同于sample_rate=16000。

(警告) 转写服务会在音频检查时,重新检测音频本身的采样率,并以检测后的结果为准。

channel int 否 音频文件的通道数。 默认为1,如果指定为多个通道,会导致最后的转写结果结构会发生变化。
sample_bytes int 否

音频文件的采样位数。

默认2,表示2个字节(16位)

slice_num int 是 音频分片总数。 用于最后的分片上传数量检查

 



【响应】:

{
  errno: 0,
  error: "",
  data: {
    audio_id: "383e72a47557490aa05a344074117a9d",  // 音频ID,创建任务的API会用到。 72小时之内有效
  }
}

 

  • 文件分片上传

【地址】:/lasr-file-api/v2/audio/{audio_id}/slice/{slice_index}?productId={PRODUCT_ID}&apiKey={APIKEY}

【请求】:

方式:POST

请求头:Content-Type: multipart/form-data

  1. 为了更好的保障大文件的传输稳定性和效率,建议分片单次不要超过4M。 4M之内,无需分片(slices_num = 1, slice_index = 0)
  2. 单次上传的文件会在服务器保存3天。
  3. 3天内可以针对文件重复创建转写任务。

 

 

参数:

参数

类型

必须

说明

productId string 否

客户编号,唯一。 QUERY STRING

audio_id string 是

创建任务时,服务器返回的audio_id。

最后根据audio_id合并所有的分片。

slice_index int 是 本次上传的分片索引编号,从0开始。QUERY STRING
file File 是 要上传的文件分片。

例子:

curl -i -X POST -H "Content-Type=multipart/form-data" -d file=@file_path /lasr-file-api/v2/audio/{audio_id}/slice/{slice_index}?productId={PRODUCT_ID}


【响应】:

{
  errno: 0, //本次分片是否保存成功, 0为成功, 非0, error字段会有具体信息
  error: "",
  data: {
    slices: 0,   // 0 ~ slices_num, 服务器已成功保存的分配总数
  }
}

 

  • 创建任务并开始转写

【地址】:/lasr-file-api/v2/task?productId={PRODUCT_ID}&apiKey={APIKEY}

【请求】:

方式:POST

请求头:Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数:

参数

类型

必须

说明

productId string 是 客户编号,唯一。 QUERY STRING
audio_id string 和file_path二选一 分片上传完成后的audio_id。(72小时内有效)
file_path string 和audio_id二选一

音频文件的HTTP下载地址。 可选:值可以为一个可以下载的HTTP地址(http地址格式不正确或不能正常下载都会报错), 或者空字符串。

(警告) 如果下载的地址里包含中文,需要把中文的文件名和路径名进行urlencode。

audio_type string 否(有file_path时必选)

音频文件的格式。

可选值:

pcm

wav

ogg_speex

ogg_opus

mp3

opus

aac

m4a

lang string 否

语种支持。

可选值: cn(默认值, 中文), en(英文), ce(中英文混合),sichuantone-mix(四川话+普通话), cantonese-mix(粤语+普通话)

当客户端没有传lang参数时,等同于lang=cn。

sample_rate int 否

音频文件的采样率。

可选值: 16000(默认值), 8000

客户端没有传递sample_rate参数时,等同于sample_rate=16000。

(警告) 转写服务会在音频检查时,重新检测音频本身的采样率,并以检测后的结果为准。

speaker_rate int 否

说话人聚类使用的采样率。

可选值: 16000(默认值同sample_rate), 8000

客户端没有传递speaker_rate参数时,等同于sample_rate。

speaker_rate设置为8000时,会导致即使sample_rate为16000时,说话人仍然使用8000采样率的资源。

channel int 否

音频文件的通道数。 默认为1,如果指定为多个通道,会导致最后的转写结果结构会发生变化:双通道分离后会有两个子任务,实际转写结果为两个子任务的结果

sample_bytes int 否

音频文件的采样位数。

默认2,表示2个字节(16位)

use_txt_smooth int 否 口语顺滑开关。0:不使用,1:使用(默认)。
use_inverse_txt int 否 逆文本转换开关。0:不使用,1:使用(默认)。
lmid string 否 自训练模型文件LMID。对应的二路模型文件在:<CUSTOME_LM_FILES_ROOT>/<lmid>/RS_latest/utterances.pat, 具体见:长语音/一句话资源分发设计
sensitive_file_id string 否 用户的敏感词文件ID。绝对路径为: <SENSITIVE_FILES_ROOT>/<sensitive_file_id>/v1/sensitive.bin, 具体见:长语音/一句话资源分发设计
phrase_file_id_new string 否

产品级热词。内容为产品级的skillId 需要在/data/share/resserver/lasr_dict_dir_res下有对应文件

phrase_list string 否 请求级热词。json格式 [{"name":"location","words":["word1","word2"],"boost":1}] 1.目前支持3种槽位:name, location, common 2.热词总词数(包含3种槽位)小于等于1500个 3.单个热词的字数2~10个字
callback string 否 识别完成时的回调HTTP(s)地址。当设置了callback地址,当识别完成后,会把最终结果以POST方式回传(也可以通过/lasr/task/result的方式来主动获取)。
speaker_number int 否

发音人个数,可选值:-1 - 8。0:表示跳过说话人聚类, 默认值 。>0:音频里发音人个数。-1:盲分。

备注:

  1. 跳过说话人聚类时,任务的最终result里,没有speaker信息。
  2. 跳过说话人聚类时,任务的最终metrics指标里,没有diarizated_t。
use_aux int 否 是否返回情绪(emotion) / 年龄(age) / 性别(gender)信息。 默认值:0, 不返回。 设置为1时,返回值里回增加emotion, age, gender, emotionScore字段。
use_segment int 否 是否返回每个分词的信息。默认值:0, 不返回。可选值: 0, 1

use_fullstop

int 否 是否以中文句号作为分句。默认值:0。值为1时开启。
use_paragraph int 否 是否在分词结果中增加语义分段标志。默认值:0。值为1时开启。本参数仅限use_segment=1时有效
use_confidence int 否 置信度总开关。默认值:0。值为1时开启。
use_nbest_confi int 否 句级别置信度总开关。默认值:0。值为1时开启。
use_word_confi int 否 词级别置信度总开关。默认值:1。值为1时开启 0关闭。
use_volume_detection
int 否 是否返回音量
use_audio_detection int 否 音频检测
use_pinyin
int 否 返回拼音

 

【响应】:

{
  errno: 0,
  error: "",
  data: {
    task_id: "383e72a47557490aa05a344074117a9d",  // 任务ID,接下来的API都会用到
  }
}

 

  • 查询转写进度

【地址】:/lasr-file-api/v2/task/<task_id>/progress?productId={PRODUCT_ID}&apiKey={APIKEY}

【请求】:

方式:GET

参数:

参数

类型

必须

说明

productId string 否

客户编号,唯一。

task_id string 是 任务ID(创建转写任务接口返回值)

 

【响应】:

{
  errno: 0,
  error: "",
  data: {
    progress: 0, //0 ~ 100,100标注转写完成
  }
}

 

  • 查询转写结果

【地址】:/lasr-file-api/v2/task/<task_id>/result?productId={PRODUCT_ID}&apiKey={APIKEY}

【请求】:

方式:GET

参数:

参数

类型

必须

说明

productId string 否

客户编号,唯一。

task_id string 是 任务ID(创建转写任务接口返回值)

 

【响应】:

单通道音频转写结果:

{
  errno: 0,
  error: "",
  data: {
    "metrics": {},
    "request": {},
    "result": [
      {
        bg: 0,                                       // 分句开始时间,ms
        ed: 4950,                                    // 分句结束时间,ms
        onebest: "思必驰信息科技有限公司。",         // 分句文本
        speaker: 0,                                  // 说话人编号
        auxinfo: {
          emotion: "",                               // 情绪
          age: "",                                   // 年龄
          gender: ""                                 // 性别
        },
        staff: "",                                    // 工作人员的vpr uid。 这段音频如果不是工作人员说的,字段值为空。 只有创建任务参数organization和vpr_uid同时包含才会生效
       },
       ...
     ],
   "segment": [
    {
      bg: 0,
      ed: 4950,
      speaker:0,
      onebest: "思必驰。"
      wp: 'n',
     },
     ...
    ]
  }
}

多通道音频转写结果:

{
  errno: 0,
  error: "",
  data: {
     
    "request": {},
    "channels": [
      //第一个通道
      {
         errno: 0,
         error: "",
         metrics: {},
         result: [
          {
             bg: 0,                                       // 分句开始时间,ms
             ed: 4950,                                    // 分句结束时间,ms
             onebest: "思必驰信息科技有限公司。",         // 分句文本
             speaker: 0,                                  // 说话人编号
             auxinfo: {
               emotion: "",                               // 情绪
               age: "",                                   // 年龄
               gender: ""                                 // 性别
             },
             staff: "",                                    // 工作人员的vpr uid。 这段音频如果不是工作人员说的,字段值为空。 只有创建任务参数organization和vpr_uid同时包含才会生效
             }
           },
           ...
           ],
         segment: [
          {
             bg: 0,
             ed: 4950,
             onebest: "思必驰信息科技有限公司。",
             speaker:0,
             wp: 'n',
           },
           ...
           ]
        },
 
        { errno: 1001, error: "no result", result: null }, //第二个通道,该通道无转写结果
 
        //第三个通道
        {
           errno: 0,
           error: "",
           metrics: {},
           result: [
           {
             bg: 0,
             ed: 4950,
             onebest: "思必驰信息科技有限公司。",
             speaker:0,
             auxinfo: {
               emotion: "",
               age: "",
               gender: ""
              }
            },
             ...
            ],
         segment: [
          {
             bg: 0,
             ed: 4950,
             onebest: "思必驰信息科技有限公司。",
             speaker:0,
             wp: 'n',
           },
           ...
           ]
          },
 
          ... //第N个通道
      ]
   }
}

 

字段说明:

bg:开始时间(ms)

ed:结束时间(ms)

onebest:识别文本

speaker:说话人序号

wp: 词性。 n普通词、s口语顺滑词标识、p标点词标识、g分段标识

emotion:情绪。 可选值: angry / happy / sad / neutral

age:年龄。 可选值:child / adult / elder

gender:性别。 可选值: female / male

staff:工作人员的vpr uid。 这段音频如果不是工作人员说的,字段值为空。 只有创建任务参数organization和vpr_id同时包含才会生效

 

错误码

转写任务的结果中,当errno=0时,有正常的任务数据data属性,当errno不等于0时,data为null。具体含义如下:

errno

error

说明

1 internal error 服务器内部错误
2 method %s not allowed. 请求方法错误
10 %s is empty or not exists. current: %s 客户端参数缺失
11 signa failed signa验证失败
12 Invalid file_path / Invalid callback

 

客户端参数里的url格式不对, 如file_path, callback
13 unknown request path: %s 未知的请求路径
101   查询任务信息失败
102   创建任务失败
103   更新任务信息失败
201 download failed, length: %d, status code: %d, message: %s. 音频下载失败
202 cut audio failed. path: %s, return code: %d 音频切割失败
203 save origin audio failed. cause: %s 音频保存失败或路径有异常
204 channel split failed 双声道音频分离失败
210   创建音频失败
211   上传的音频片段编号不对,要按顺序依次上传,禁止并发
212   上传的音频片段太小,必须超过100K
213   上传的音频片段size小于0
301   音频后处理失败
302 timeout 音频处理超时
501 file not exist. path: %s 要加载的音频文件不存在
502   识别异常