更新时间:2024-03-14 GMT+08:00
分享

提交录音文件识别任务

录音文件识别接口,用于识别长录音文件,支持中文普通话、四川话识别。录音文件放在OBS(对象存储服务)或公网可访问的服务器上。

由于录音文件识别通常会需要较长的时间,因此识别是异步的,即接口分为创建识别任务和查询任务状态两个接口。创建识别任务接口创建任务完成后返回job_id参数,然后用户通过调用录音文件识别状态查询接口来获得转写状态和结果。

功能介绍

该接口用于提交录音文件识别任务,其中录音文件保存在用户的OBS桶中或公网可访问的服务器上(需保证可使用域名访问)。用户开通录音识别服务时,如果录音文件存放在OBS桶中,需授权录音文件引擎读取用户OBS桶权限,授权方法见配置OBS访问权限。该接口的使用限制请参见约束与限制,详细使用指导请参见SIS服务使用简介章节。

SIS服务控制台提供了录音文字识别的在线使用页面,用户无需编程即可使用服务功能。

图1 在线使用

调试

您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。

接口约束

  • 录音时长不超过5小时,文件大小不超过300M。8k采样率音频最小为1.6kb,16k采样率音频最小为3.2kb,即音频时长至少0.1s以上。
  • 需要将识别的录音文件存放在某服务上,可以通过URL访问。
    • 推荐使用华为云OBS:授权配置请参见配置OBS服务,优先推荐使用与请求服务同一region的私有桶文件,如果region不一致,可考虑使用obs签名
    • 您也可以把录音文件放在自行搭建服务器上,提供下载文件的地址。URL不能使用IP地址,只能使用域名,请尽量避免中文。
  • 音频转写时长受音频时长和排队任务数量影响,音频时长和理论返回时间可参见表 音频转写时长参考表。如果转写耗时比理论时延长,大概率表示当前时间段出现转写高峰,请耐心等待,我们承诺最大转写时长不超过6小时。
    表1 音频转写时长参考表

    音频时长

    参考返回时间

    小于10分钟

    小于2分钟

    10分钟-60分钟

    2分钟-12分钟

    大于60分钟

    12 分钟-60分钟

  • 识别结果保存72小时(从识别完成的时间算起)。72小时后如果再访问,将会返回 "task id is not found"错误。

URI

POST /v1/{project_id}/asr/transcriber/jobs

表2 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目编号。获取方法,请参见获取项目ID

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

用于获取操作API的权限。获取方法请参见认证鉴权。响应消息头中X-Subject-Token的值即为Token。

Enterprise-Project-Id

String

企业项目ID。SIS支持通过企业项目管理(EPS)对不同用户组和用户的资源使用,进行分账。

获取方法:进入“企业项目管理”页面,单击企业项目名称,在企业项目详情页获取Enterprise-Project-Id(企业项目ID)。

企业项目创建步骤请参见用户指南。

说明:

创建企业项目后,在传参时,有以下三类场景。

  • 携带正确的ID,正常使用SIS服务,账单归到企业ID对应的企业项目中。
  • 携带错误的ID,正常使用SIS服务,账单的企业项目会被分类为“default”。
  • 不携带ID,正常使用SIS服务,账单的企业项目会被分类为“default”。
表4 请求Body参数

参数

是否必选

参数类型

描述

config

TranscriberConfig object

录音文件识别配置信息。

data_url

String

存放录音文件地址:

  • 推荐使用华为云OBS:授权配置请参见配置OBS服务
  • 您也可以把录音文件放在自行搭建服务器上,提供下载文件的地址。URL不能使用IP地址,只能使用域名,请尽量避免中文。
表5 TranscriberConfig

参数

是否必选

参数类型

描述

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(中文普通话语音识别)
  • chinese_16k_conversation(会议场景的中文普通话语音识别)
  • sichuan_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,请求体参见表 响应参数

  • 如果用户使用回调方式获取识别结果,需填写该参数,处理成功后用户服务器需返回状态码“200”
  • 如果用户使用轮询方式获取识别结果,则无需填写该参数。

digit_norm

String

表示是否将语音中的数字识别为阿拉伯数字,取值为yes 、 no,默认为yes。

need_analysis_info

AnalysisInfo object

该参数用于设置质检分析参数,是否需要输出质检分析内容以及会议场景多说话人分离,如果为null , 表示不需要。

vocabulary_id

String

热词表id,不使用则不填写。

创建热词表信息请参考创建热词表

need_word_info

String

表示是否在识别结果中输出分词结果信息,取值为“yes”“no”,默认为“no”

表6 AnalysisInfo

参数

是否必选

参数类型

描述

diarization

Boolean

是否需要做话者分离。

默认为true,表示会进行话者分离,识别结果中会包含role项(角色)。

如果diarization为false,那么结果中不会出现role项。

说明:

本表中的参数对audio_format格式中采样率为8k和16k的音频有效。对于8k单声道音频,8k双声道音频以及16k双声道音频仅支持两个说话人分离;对于16k单声道音频,自动识别说话人个数,返回结果最多支持10个说话人,并且property仅支持chinese_16k_media,区域仅支持cn-east-3。

channel

String

语音文件声道信息,默认为MONO,可设置为MONO,LEFT_AGENT, RIGHT_AGENT。

如果channel 为MONO,那么原始文件需要为单声道文件。

如果为双声道文件,系统会将其转换成单声道文件,可能会影响识别效果。

如果 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。

表7 audio_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参数,然后用户通过调用录音文件识别状态查询接口来获得转写状态和结果。

状态码: 400

表9 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

“endpoint”即调用API的请求地址,不同服务不同区域的“endpoint”不同,具体请参见终端节点

  • 提交录音文件识别任务
    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":"***"
}

状态码

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品