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 流程说明
3.2 产品创建与授权
3.2.1 创建基础技术产品
集成录音文件长语音转写API,需要先创建基础技术服务产品。
- 登录DUI控制台后,点击导航栏的【基础技术】,进入基础技术产品列表页。
- 在列表页,点击【基础技术接入】,创建基础技术产品,选择接实时转写服务。

- 选择需要接入的录音文件转写服务。

3.2.2 产品授权
- 进入基础技术产品详情页, 点击【授权管理】,进入授权页。
- 在授权页,根据业务需求,选择授权方式。云端对云端的情况请选择 【服务授权】。

- 选择【配置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 | 是 | 音频分片总数。 用于最后的分片上传数量检查 |
【响应】:
|
|
-
文件分片上传
【地址】:/lasr-file-api/v2/audio/{audio_id}/slice/{slice_index}?productId={PRODUCT_ID}&apiKey={APIKEY}
【请求】:
方式:POST
请求头:Content-Type: multipart/form-data
- 为了更好的保障大文件的传输稳定性和效率,建议分片单次不要超过4M。 4M之内,无需分片(slices_num = 1, slice_index = 0)
- 单次上传的文件会在服务器保存3天。
- 3天内可以针对文件重复创建转写任务。
参数:
|
|
|
|
|
|---|---|---|---|
| productId | string | 否 |
客户编号,唯一。 QUERY STRING |
| audio_id | string | 是 |
创建任务时,服务器返回的audio_id。 最后根据audio_id合并所有的分片。 |
| slice_index | int | 是 | 本次上传的分片索引编号,从0开始。QUERY STRING |
| file | File | 是 | 要上传的文件分片。 |
例子:
|
|
【响应】:
|
|
-
创建任务并开始转写
【地址】:/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:盲分。 备注:
|
| 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 | 否 | 返回拼音 |
【响应】:
|
|
-
查询转写进度
【地址】:/lasr-file-api/v2/task/<task_id>/progress?productId={PRODUCT_ID}&apiKey={APIKEY}
【请求】:
方式:GET
参数:
|
参数 |
类型 |
必须 |
说明 |
|---|---|---|---|
| productId | string | 否 |
客户编号,唯一。 |
| task_id | string | 是 | 任务ID(创建转写任务接口返回值) |
【响应】:
|
|
-
查询转写结果
【地址】:/lasr-file-api/v2/task/<task_id>/result?productId={PRODUCT_ID}&apiKey={APIKEY}
【请求】:
方式:GET
参数:
|
参数 |
类型 |
必须 |
说明 |
|---|---|---|---|
| productId | string | 否 |
客户编号,唯一。 |
| task_id | string | 是 | 任务ID(创建转写任务接口返回值) |
【响应】:
|
|
多通道音频转写结果:
|
|
字段说明:
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 | 识别异常 |