# 提交录音文件识别任务 - PushTranscriberJobs 录音文件识别接口，用于识别长录音文件，支持中文普通话、四川话识别。录音文件放在OBS（对象存储服务）或公网可访问的服务器上。 由于录音文件识别通常会需要较长的时间，因此识别是异步的，即接口分为创建识别任务和查询任务状态两个接口。创建识别任务接口创建任务完成后返回job_id参数，然后用户通过调用[录音文件识别状态查询](https://support.huaweicloud.com/api-sis/sis_03_0093.html)接口来获得转写状态和结果。 #### 功能介绍 该接口用于提交录音文件识别任务，其中录音文件保存在用户的OBS桶中或公网可访问的服务器上（需保证可使用域名访问）。用户开通录音识别服务时，如果录音文件存放在OBS桶中，需授权录音文件引擎读取用户OBS桶权限，授权方法见[配置OBS访问权限](https://support.huaweicloud.com/api-sis/sis_03_0047.html)。该接口的使用限制请参见[约束与限制](https://support.huaweicloud.com/productdesc-sis/sis_01_0011.html)，详细使用指导请参见[SIS服务使用简介](https://support.huaweicloud.com/qs-sis/sis_07_0001.html)章节。 [SIS服务控制台](https://console.huaweicloud.com/sis)提供了录音文字识别的在线使用页面，用户无需编程即可使用服务功能。 图1在线使用 ![](https://support.huaweicloud.com/api-sis/zh-cn_image_0000001899699937.png "点击放大") #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=SIS&api=PushTranscriberJobs)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 接口约束 - 录音时长不超过5小时，文件大小不超过300M。且音频时长至少0.01s以上。 - 需要将识别的录音文件存放在某服务上，可以通过URL访问。 - 推荐使用华为云OBS：授权配置请参见[配置OBS服务](https://support.huaweicloud.com/api-sis/sis_03_0047.html)，优先推荐使用与请求服务同一region的私有桶文件，如果region不一致，可考虑使用[obs签名](https://support.huaweicloud.com/api-obs/obs_04_0011.html)。 - 您也可以把录音文件放在自行搭建服务器上，提供下载文件的地址。URL不能使用IP地址，只能使用域名，请尽量避免中文。 - 音频转写时长受音频时长和排队任务数量影响，音频时长和理论返回时间可参见[表 音频转写时长参考表]。如果转写耗时比理论时延长，大概率表示当前时间段出现转写高峰，请耐心等待，我们承诺最大转写时长不超过6小时。 表1音频转写时长参考表 | 音频时长 | 参考返回时间 | |:---|:---| | 小于10分钟 | 小于2分钟 | | 10分钟-60分钟 | 2分钟-12分钟 | | 大于60分钟 | 12 分钟-60分钟 | - 识别结果保存72小时（从识别完成的时间算起）。72小时后如果再访问，将会返回 "task id is not found"错误。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/usermanual-sis/sis_09_0016.html)。 #### URI POST /v1/{project_id}/asr/transcriber/jobs 表2路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目编号。获取方法，请参见[获取项目ID](https://support.huaweicloud.com/api-sis/sis_03_0008.html)。 | #### 请求参数 表3请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | 用户Token。 用于获取操作API的权限。获取方法请参见[认证鉴权](https://support.huaweicloud.com/api-sis/sis_03_0058.html)。响应消息头中X-Subject-Token的值即为Token。 | | Enterprise-Project-Id | 否 | String | 企业项目ID。SIS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入"[企业项目管理](https://console.huaweicloud.com/eps/?#/eps/manager/projects)"页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 ![](https://support.huaweicloud.com/api-sis/zh-cn_image_0000001643616153.png "点击放大") 企业项目创建步骤请参见用户指南。 说明： 账户创建企业项目后，在传参时，有以下三类场景。 - 携带正确的ID，正常使用SIS服务，账单归到企业ID对应的企业项目中。 - 携带错误的ID，正常使用SIS服务，账单的企业项目会被分类为"default"。 - 不携带ID，正常使用SIS服务，账单的企业项目会被分类为"default"。 | 表4请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | config | 是 | [TranscriberConfig] Object | 录音文件识别配置信息。 | | data_url | 是 | String | 存放录音文件地址： - 推荐使用华为云OBS：授权配置请参见[配置OBS服务](https://support.huaweicloud.com/api-sis/sis_03_0047.html)。 - 您也可以把录音文件放在自行搭建服务器上，提供下载文件的地址。URL不能使用IP地址，只能使用域名，请尽量避免中文。 | 表5TranscriberConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | audio_format | 否 | String | 支持语音的格式，请参考[表 audioformat取值范围]。 | | property | 是 | String | 所使用的模型特征串。通常是"语种_采样率_领域"的形式，例如chinese_8k_common。 采样率需要与音频采样率保持一致。 当前支持如下模型特征串： - chinese_8k_general（电话通话领域，区域支持cn-north-4, cn-east-3，最新端到端通用模型，强烈推荐使用） - chinese_16k_media（音视频领域，区域支持cn-north-4，cn-east-3，强烈推荐使用） - chinese_8k_common（中文普通话语音识别，区域支持cn-north-4, cn-east-3） - chinese_16k_conversation（会议场景的中文普通话语音识别，区域支持cn-north-4, cn-east-3） - sichuan_8k_common（四川话识别，区域支持cn-north-4，cn-east-3） - shanghai_8k_common（上海话识别，区域支持cn-north-4, cn-east-3） - cantonese_8k_common（粤语识别，区域支持cn-north-4, cn-east-3） - chinese_8k_bank（银行领域，区域仅支持cn-north-4） - chinese_8k_insurance（保险领域，区域仅支持cn-north-4） | | add_punc | 否 | String | 表示是否在识别结果中添加标点，取值为yes 、 no，默认no。 | | callback_url | 否 | String | 表示回调 url，即用户用于接收识别结果的服务器地址，不支持IP地址方式调用，url长度小于2048字节。服务请求方法为POST，请求体参见[表 响应参数](https://support.huaweicloud.com/api-sis/sis_03_0093.html#sis_03_0093__table628215280284)。 - 如果用户使用回调方式获取识别结果，需填写该参数，处理成功后用户服务器需返回状态码"200"。 - 如果用户使用轮询方式获取识别结果，则无需填写该参数。 | | digit_norm | 否 | String | 表示是否将语音中的数字识别为阿拉伯数字，取值为yes 、 no，默认为yes。 | | need_analysis_info | 否 | [AnalysisInfo] Object | 是否选择分析信息。当前仅对8k模型有效。 如果选择false，则声道、话者分离、情绪检测、速度信息均无效。默认false。 该参数用于设置质检分析参数，是否需要输出质检分析内容以及会议场景多说话人分离，如果为false, 表示不需要。 | | vocabulary_id | 否 | String | 热词表id，不使用则不填写。 创建热词表信息请参考[创建热词表 - CreateVocabulary](https://support.huaweicloud.com/api-sis/sis_03_0071.html)。 | | need_word_info | 否 | String | 表示是否在识别结果中输出分词结果信息，取值为"yes"和"no"，默认为"no"。 | 表6AnalysisInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | diarization | 否 | Boolean | 是否需要做话者分离。 默认为true，表示会进行话者分离，识别结果中会包含role项（角色）。 如果diarization为false，那么结果中不会出现role项。 说明： 本表中的参数对audio_format格式中采样率为8k和16k的音频有效。对于8k单声道音频，8k双声道音频以及16k双声道音频仅支持两个说话人分离；对于16k单声道音频，自动识别说话人个数，返回结果最多支持10个说话人，并且property仅支持chinese_16k_media。 | | channel | 否 | String | 语音文件声道信息，默认为MONO，可设置为MONO，LEFT_AGENT, RIGHT_AGENT。 如果channel 为MONO，那么原始文件需要为单声道文件；如果channel 为MONO，diarization为true时，会默认输出speed结果。 如果为双声道文件，系统会将其转换成单声道文件，可能会影响识别效果。 如果 channel 为 LEFT_AGENT或RIGHT_AGENT, 则原始文件需要为双声道文件，如果为单声道文件，系统会将其转换成双声道文件，识别结果会出现两条内容完全一致的文本。 当channel 为 LEFT_AGENT或RIGHT_AGENT，且diarization为true时，系统会按照配置给出对应角色。其中： - LEFT_AGENT 指定左声道语音为agent（坐席）。 - RIGHT_AGENT 指定右声道为agent（坐席）。 | | emotion | 否 | Boolean | 是否需要做情绪检测，默认为true。仅对audio_format格式中采样率为8k的音频有效。 目前支持NORMAL（正常）、ANGRY（愤怒）和UNKNOWN（未知）情绪识别。 | | speed | 否 | Boolean | 是否需要输出语速信息，默认为true。 | 表7audio_format取值范围 | audio_format取值 | 描述 | |:---|:---| | auto | 默认格式，系统自动判断，支持的音视频格式如下：WAV（内部支持pcm/ulaw/alaw/adpcm编码格式）、AMR、FLAC、M4A、mp3、OGG、WEBM、AAC、AC3、MOV、WMA、MP4、AVI、RMVB、MKV、FLV、F4V、WMV、3GP。支持双声道的音视频。 | | pcm16k16bit | 16k16bit裸音频录音数据。 | | pcm8k16bit | 8k16bit裸音频录音数据。 | | ulaw16k8bit | 16k8bit ulaw 裸音频录音数据。 | | ulaw8k8bit | 8k8bit ulaw 裸音频录音数据。 | | alaw16k8bit | 16k8bit alaw 裸音频录音数据。 | | alaw8k8bit | 8k8bit alaw 裸音频录音数据。 | #### 响应参数 **状态码： 200** 表8响应Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | job_id | 否 | String | 创建的任务标识, 如果创建任务成功时必须存在。 由于录音文件识别通常会需要较长的时间，因此识别是异步的，即接口分为创建识别任务和查询任务状态两个接口。 创建识别任务接口创建任务完成后返回job_id参数，然后用户通过调用[录音文件识别状态查询](https://support.huaweicloud.com/api-sis/sis_03_0093.html)接口来获得转写状态和结果。 | **状态码： 400** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 调用失败时的错误码。 调用成功时无此字段。 | | error_msg | String | 调用失败时的错误信息。 调用成功时无此字段。 | #### 请求示例 ![](https://support.huaweicloud.com/api-sis/public_sys-resources/note_3.0-zh-cn.png) "endpoint"即调用API的请求地址，不同接口不同区域的"endpoint"不同，具体请参见[终端节点](https://support.huaweicloud.com/api-sis/sis_03_0004.html)。 - 提交录音文件识别任务 ``` POST https://{endpoint}/v1/1609d8170cd86660a81281e5a3a03f8b/asr/transcriber/jobs Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG... Request Body: { "config": { "audio_format": "auto", "property": "chinese_8k_general", "add_punc": "yes", "need_analysis_info": { "diarization": true, "channel": "LEFT_AGENT", "emotion": true }, "need_word_info": "yes" }, "data_url":"https://****_voip.obs.myxxxcloud.com/VOIP/***.wav" } ``` - 使用Python3语言提交录音文字识别任务 ``` # -*- coding: utf-8 -*- # 此demo仅供测试使用，强烈建议使用sdk。需提前安装requests，执行pip install requests import requests import time import json def lasr_demo(): url = 'https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs' # endpoint和project_id需替换 token = '用户对应region的token' obs_url = 'obs路径' header = { 'Content-Type': 'application/json', 'X-Auth-Token': token } body = { 'data_url': obs_url, 'config': { 'property': 'chinese_8k_general', 'audio_format': 'auto' } } resp = requests.post(url, data=json.dumps(body), headers=header) job_id = json.loads(resp.text, encoding='utf-8')['job_id'] query_task(header, job_id) def query_task(header, job_id): # endpoint和project_id需替换 url = 'https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs/' + job_id for _ in range(1000): resp = requests.get(url, headers=header) print(resp.text) if resp.text.find('segments') != -1: break time.sleep(1) if __name__ == '__main__': lasr_demo() ``` - 使用Java语言提交录音文件识别任务 ``` import java.io.BufferedReader; import java.io.InputStream; import java.io.InputStreamReader; import java.io.OutputStreamWriter; import java.net.HttpURLConnection; import java.net.URL; /** * 此demo仅供测试使用，强烈建议使用SDK */ public class LasrDemo { public void lasrDemo() { try { // endpoint和projectId需要替换成实际信息。 URL url = new URL("https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs"); String token = "对应region的token"; String obsUrl = "音频在obs的路径"; HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setRequestMethod("POST"); connection.setDoInput(true); connection.setDoOutput(true); connection.addRequestProperty("Content-Type", "application/json"); connection.addRequestProperty("X-Auth-Token", token); OutputStreamWriter osw = new OutputStreamWriter(connection.getOutputStream(), "UTF-8"); String body = "{\"data_url\":\"" + obsUrl + "\", \"config\": { \"audio_format\": \"auto\", " + "\"property\":\"chinese_8k_general\"}}"; osw.append(body); osw.flush(); InputStream is = connection.getInputStream(); BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8")); String jobId = ""; while (br.ready()) { String line = br.readLine().trim(); jobId = line.replace("{\"job_id\":\"", "").replace("\"}", ""); } queryTask(token, jobId); } catch (Exception e) { e.printStackTrace(); } } private void queryTask(String token, String jobId) { try { // endpoint和projectId需要替换成实际信息。 URL url = new URL("https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs/" + jobId); while (true) { HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setRequestMethod("GET"); connection.setDoInput(true); connection.setDoOutput(true); connection.addRequestProperty("Content-Type", "application/json"); connection.addRequestProperty("X-Auth-Token", token); InputStream is = connection.getInputStream(); BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8")); if (br.ready()) { String line = br.readLine(); System.out.println(line); if (line.contains("segments")) { break; } } Thread.sleep(2000); } } catch (Exception e) { e.printStackTrace(); } } public static void main(String[] args) { LasrDemo lasrDemo = new LasrDemo(); lasrDemo.lasrDemo(); } } ``` #### 响应示例 **状态码：200** 成功响应示例 ``` { "job_id": "567e6536-a89c-13c3-a882-826321939656" } ``` **状态码：400** 失败响应示例 ``` { "error_code":"SIS.0002", "error_msg":"***" } ``` #### 状态码 状态码请参见[状态码](https://support.huaweicloud.com/api-sis/sis_03_0044.html)。 #### 错误码 错误码请参见[错误码](https://support.huaweicloud.com/api-sis/sis_03_0045.html)。