调用UploadAudioData上传音频质检_智能对话分析-阿里云帮助中心

上传离线语音质检数据（录音会话文件）：适用于热线坐席场景。场景1：天然集成阿里云呼叫中心（CCC），无需开发，可以一键开启推送通话数据到SCA；场景2：与自有呼叫中心系统对接，呼叫中心每产生一条录音，就将录音推送至SCA进行分析。

接口说明

流程说明

API调用上传音频质检=>录音文件转文本=>根据指定的分轨方式对文本进行角色分离（区分客服、客户）=>使用质检规则进行分析=>质检完成。

任务执行效率说明

任务执行的快慢，取决于录音文件转文本的快慢，理想情况下，一个长度为5分钟的录音文件，可以在2分钟内转写完成，但是遇到文件转写服务排队任务较多时，会有一个排队等待的时间，一般会在6小时内转写完成，一次性上传大规模数据（半小时内上传超过500小时时长的录音）的除外。转写完成后，质检分析的速度是毫秒级的。

录音文件URL要求

持单轨/双轨的wav格式、mp3格式的录音文件，文件大小需要控制在512M以下。
URL必须是基于HTTP可访问的URL地址，不支持提交本地文件；录音文件访问权限需要为公开。
URL中只能使用域名，不能使用IP地址，URL中不可包含空格，请尽量避免使用中文。
系统在录音转文本后，会将下载的录音文件删除，不会保存录音副本
若您的录音URL是存在访问有效期的，例如录音存储在阿里云OSS，通过OSS生成录音URL时指定了有效期，建议有效期至少为12小时，如果条件允许，最好设置为24小时。这样做是因为文件转写需要一定的时间，并且偶尔会产生排队等待，若排队时间较长，开始转写时才会下载录音，避免下载录音时录音URL已失效的情况发生。
质检分析完成后，在控制台复核文件时，播放录音使用的仍然是您提供的URL，所以需要保证URL长期可用，否则将无法播放录音。

角色分离说明

录音转文本后，系统会自动将文本分为两个对话角色，但是系统无法判断哪个角色是客服、哪个是客户。所以需要您来根据某些规则进行角色分离。角色分离的准确性非常重要，因为我们进行质检分析时所用的规则，很多时候都有检测角色的限制（即一个规则只检测客服或者客户），如果角色分离错误，那么将对质检结果的准确性产生极大影响。

录音文件通常分为单轨（单声道）和双轨（双声道/立体声）两种：

单轨录音：客服、客户两个人的声音存储在一个轨上，在录音文件转文本后，系统会通过内置算法区分为两个角色的对话，通过设置一组客服可能说的关键词列表，通过对转写文本从上到下逐句分析，当一句话命中某一个关键词时，则判定该句的角色为客服，则另一个角色就是客户，具体使用详见请求入参中的recognizeRoleDataSetId和serviceChannelKeywords。由于对话内容的不可控性（比如两个角色对话存在交叉，两个人同时讲话），所以单轨录音的角色分离无法保证100%准确，强烈建议在保存录音文件时保存为双轨录音。
双轨录音：客服、客户两个人的声音分别存储在两个轨上，即使两个角色的对话存在交叉录音转文本时可以准确的区分为两个角色，所以直接通过请求参数中的serviceChannel、clientChannel来指定客服、客户即可。

获取质检分析结果

由于录音文件识别是非实时的，所以需要异步获取质检分析结果，有以下3种方式获取结果：

消息通知：详情请查看消息队列，收到消息后再通过GetResult接口获取详细结果。（推荐）
回调：通过在请求参数中指定callbackUrl，在任务完成后由系统主动发起回调；接到回调后再通过GetResult接口获取详细结果。
轮询：接口会返回任务ID（taskId），可以用taskId轮训getResult接口异步获取结果，判断返回参数中的status是否完成，轮询间隔建议不要太短，正常情况下会在几分钟内分析完成，建议轮询间隔在30s以上。（不推荐）。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求参数

名称	类型	必填	描述	示例值
JsonStr	string	是	完整JSON字符串信息，具体内容参见以下详细信息。	{“callList”:“xxxxx”}

请求参数与JSON字符串信息

属性	值类型	是否必须	描述
isSchemeData	Integer	否	是否将数据上传至新版智能对话分析，取值：0：否；1：是，默认值为0。
callList	List	是	语音文件集合，可以一次性上传多个录音文件，详见下方的jsonStr.callList属性说明。
autoSplit	Integer	否	多数情况下适用于单轨录音，取值：0、1，是否自动分轨，1为自动分轨，0为不分轨；默认：1；若指定为1，则表示上传的音频为单轨；自动分轨会额外占用处理时间。若录音为双轨录音，该参数必须传0。
recognizeRoleDataSetId	Long	否	数据集ID，使用一个已存在的数据集，因为数据集在创建时会设置角色分离规则（可以查看新建数据集功能中的话者角色配置），此处指定数据集ID，则本次上传的文件会复用此数据集的角色分离规则。适用于单轨录音。
serviceChannelKeywords	List	否	多数情况下适用于单轨录音，设置一组客服可能说的关键词列表（请确保选择那些区别性比较高的关键词），通过对转写文本从上到下逐句分析，当一句话命中某一个关键词时，则判定该句的角色为客服，则另一个角色就是客户。当recognizeRoleDataSetId和serviceChannelKeywords都存在时，recognizeRoleDataSetId优先级更高；若两者均未设置，则使用系统内置的分轨规则进行兜底。
serviceChannel	Integer	否	适用于双轨录音，指定客服角色的轨道编号，取值：0、1，默认0，即第0轨为客服；通常音轨都是从0开始编号，2个轨就是0，1；具体0是客服还是客户，需要您自行确认。若使用此参数，请务必传入autoSplit参数，值为0。若单轨文件忽略此参数。
clientChannel	Integer	否	适用于双轨录音，指定客户角色的轨道编号，取值：0、1，默认1，即第1轨为客户；通常音轨都是从0开始编号，2个轨就是0，1；具体0是客服还是客户，需要您自行确认。若使用此参数，请务必传入autoSplit参数，值为0。单轨文件忽略此参数。
ruleIds	List	否	规则ID列表，用于指定录音文件使用哪些规则进行质检分析，若不指定，则会过所有规则；注意：单个文件允许最大规则数为100，如果超过100，则会截取前100个规则。（只能使用离线质检规则，不可使用实时质检规则）（新版不适用，仅旧版智能对话分析适用）
ruleBusinessNames	List	否	适用业务列表，系统会使用这些适用规则所关联的规则进行质检分析。与ruleIds不同，该参数适用于规则经常变化的场景：新建规则时，将规则与对应的适用业务关联即可，这样增加了新的规则，不需要修改请求参数，就可以使用新建的规则进行质检分析。（新版不适用，仅旧版智能对话分析适用）
sampleRate	Integer	否	录音文件的采样率，可选值：8（8000hz）；16（16000hz）；默认8。需要正确指定录音文件采样率，错误的采样率会导致转写结果错误，通常呼叫中心产生的录音采样率是8000hz。
callbackUrl	String	否	回调地址，不指定则不回调，请保证回调地址公网可访问，不支持ip；录音分析完成后会发起回调；详细说明请查看下方的回调参数说明
vocabId	String	否	热词模型ID，不指定则不使用热词；ID值可以从控制台的"基础设置"->"热词"->"热词组ID"中查看。
modelId	String	否	语言模型ID，不指定则使用通用模型；ID值可以从控制台的"基础设置"->"语言模型"中查看。
baseModelId	String	否	基础模型ID，取值：mandarin（中文普通话8k，默认），mandarin16（中文普通话16k），cantonese（粤语，需要开通白名单）；默认：mandarin。

jsonStr.callList属性说明：

属性	值类型	是否必须	描述
voiceFileUrl	String	是	录音文件，具体要求详见API说明中的录音文件URL要求
fileName	String	否	音频文件名称，如audio.wav；虽不是必填项，但为方便统计，请尽量提供此参数；若不提供，则会从voiceFileUrl中获取，比如http://www.aliyun.com/audio.wav，则文件名解析为：audio.wav。
autoSplit	Integer	否	参见上层对象参数说明；如为空，会采用上层对象对应值。
recognizeRoleDataSetId	Long	否	参见上层对象参数说明；如为空，会采用上层对象对应值。
serviceChannel	Integer	否	参见上层对象参数说明；如为空，会采用上层对象对应值。
clientChannel	Integer	是	参见上层对象参数说明；如为空，会采用上层对象对应值。
sampleRate	Integer	否	参见上层对象参数说明；如为空，会采用上层对象对应值。
callStartTime	Long	否	录音发生的时间，格林威治时间1970年01月01日00时00分00秒到现在的毫秒数（即毫秒时间戳，例如：1584535485856），若不指定，则会取当前时间。
vocabId	String	否	参见上层对象参数说明；如为空，会采用上层对象对应值。
customerServiceId	Long	否	客服ID。可从控制台-基础设置-人员管理页面获取，正确填入客服ID，客服登录控制塔时可以查看与自己关联的录音文件。
customerServiceName	String	否	客服姓名。
skillGroupId	Long	否	技能组ID。
skillGroupName	String	否	技能组名称。
callType	Integer	否	呼叫类型，可取值：1：呼出；3：呼入。
callee	String	否	被叫号码，呼出时指的是客户号码，呼入时指的是客服号码。
caller	String	否	主叫号码，呼出时指的是客服号码，呼入时指的是客户号码。
callId	String	否	通话ID，可以是呼叫中心系统中的通话ID，或者其他可以标识通话的ID。
business	String	否	业务线名称，属于自定义数据，用于分类统计。
callUuid	String	否	全局唯一标识，做幂等（排重）使用，若传入该字段，系统将查询最近两小时内上传的数据中是否存在相同的callUuid，若存在则本次上传请求将被拒绝。
sessionGroupId	String	否	会话组ID，通常把同一个客服和同一个客户的会话称之为一个会话组，当传入会话组ID后，可在会话组结果页查看会话组维度的质检结果。（仅新版智能对话分析适用）
customerId	String	否	客户ID。（仅新版智能对话分析适用）
customerName	String	否	客户姓名。（仅新版智能对话分析适用）
schemeTaskConfigId	String	否	手动指定的质检任务ID（手动指定后则会使用指定的质检任务进行质检）。（仅新版智能对话分析适用）
remark1	String	否	自定义数据1，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark2	String	否	自定义数据2，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark3	String	否	自定义数据3，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark4	String	否	自定义数据4，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark5	Long	否	自定义数据5，可以存放与您业务相关的自定义字段，格式为有符号的long型。
remark6	String	否	自定义数据6，可以存放与您业务相关的自定义字段，最大长度为1024字符。
remark7	String	否	自定义数据7，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark8	String	否	自定义数据8，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark9	String	否	自定义数据9，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark10	String	否	自定义数据10，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark11	String	否	自定义数据11，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark12	String	否	自定义数据12，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark13	String	否	自定义数据13，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark14	Long	否	自定义数据14，可以存放与您业务相关的自定义字段，格式为有符号的long型。
remark15	Long	否	自定义数据15，可以存放与您业务相关的自定义字段，格式为有符号的long型。
remark16	String	否	自定义数据16，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark17	String	否	自定义数据17，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark18	String	否	自定义数据18，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark19	String	否	自定义数据19，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark20	String	否	自定义数据20，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark21	String	否	自定义数据21，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark22	String	否	自定义数据22，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark23	String	否	自定义数据23，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark24	String	否	自定义数据24，可以存放与您业务相关的自定义字段，最大长度为64字符。
remark25	String	否	自定义数据25，可以存放与您业务相关的自定义字段，最大长度为64字符。
jsonParamStr	String	否	更多自定义字段，格式为JSON字符串，key为字段名称，value为字段内容，示例：{"客户等级"：3，"渠道"："官网"}。
complain	Boolean	否	是否客诉，用于原因分析模块，该字段若为true，则将归类到客诉原因分析数据中进行分析。
unsolved	Boolean	否	是否未解决，用于原因分析模块，该字段若为true，则将归类到未解决原因分析数据中进行分析。

回调参数说明

假设调用方传入的回调地址是：http://aliyun.com/callback，那么回调时的完整URL为http://aliyun.com/callback?taskId=xxx&timestamp=xxx&signature=xxx&event=xxx，其中：

taskId：为任务ID
timestamp：为调用时的时间戳，单位：毫秒
aliUid：为调用方阿里云主账号uid
signature：为签名，调用方可用来判断请求是否来自阿里云；计算说明：将taskId=xxx&timestamp=xxx&aliUid=xxx进行md5+base64加密，注意顺序；调用方接到回调后，taskId和timestamp可以从回调URL中获取，aliUid即为阿里云主账号ID。通过计算来比对自己计算出的signature，与URL中的signature是否一致，详见下方Java代码示例。
event：为事件名称，调用方可用来判断是什么事件触发的回调，取值为TaskComplete：任务完成时的回调；

public static void signature() {
    long timestamp = System.currentTimeMillis();
    String taskId = "xxxx";
    String aliUid = "xxxxx";
    // 将 taskId=xxx&timestamp=xxx&aliUid=xxx 进行md5 + base64加密，放在signature字段
    String signature;
    try {
        signature = URLEncoder.encode(md5Base64("taskId=" + taskId + "&timestamp=" + timestamp + "&aliUid=" + aliUid), "utf-8");
        System.out.println(signature);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

public static String md5Base64(String str) throws NoSuchAlgorithmException {
    //string 编码必须为utf-8
    byte[] utfBytes = str.getBytes(StandardCharsets.UTF_8);
    MessageDigest mdTemp = MessageDigest.getInstance("MD5");
    mdTemp.update(utfBytes);
    byte[] md5Bytes = mdTemp.digest();
    return Base64.encodeBase64String(md5Bytes);
}

请求入参示例

{
    "autoSplit":1,
    "serviceChannelKeywords":[
        "留学",
        "客服老师"
    ],
    "ruleIds":[
        181**,
        155**
    ],
    "vocabId":"a7735a24c9ef4213b2fa41d****",
    "modelId":"9706**",
    "callList":[
        {
            "voiceFileUrl":"https://sca-ccc-test.oss-cn-beijing.aliyuncs.com/****.wav",
            "fileName":"abc.wav",
            "callStartTime":"1584535485856",
            "customerServiceId":"30",
            "customerServiceName":"Aagent",
            "skillGroupId":"34sd24",
            "skillGroupName":"售前技能组",
            "callType":1,
            "callee":188888****,
            "caller":"0102323***",
            "callId":23456457**,
            "business":"售前一组",
            "remark1":"38节大促"
        }
    ]
}

返回参数

名称	类型	描述	示例值
	object	返回结果
Code	string	结果代码，200表示成功，若为别的值则表示失败，调用方可根据此字段判断失败原因。	200
Message	string	出错时表示出错详情，成功时为successful。	successful
Data	string	任务ID，在获取任务结果时使用。	76DB5D8C-5BD9-42A7-B527-5AF3A5***
RequestId	string	请求ID，请求唯一标识。	76DB5D8C-5BD9-42A7-B527-5AF3A5F8***
Success	boolean	请求是否成功，调用方可根据此字段来判断请求是否成功：true表示成功；false/null表示失败。	true

示例

正常返回示例

JSON格式

{
  "Code": "200",
  "Message": "successful",
  "Data": "76DB5D8C-5BD9-42A7-B527-5AF3A5***",
  "RequestId": "76DB5D8C-5BD9-42A7-B527-5AF3A5F8***",
  "Success": true
}

错误码

访问错误中心查看更多错误码。