文档

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暂无授权信息透出。

请求参数

名称类型必填描述示例值
JsonStrstring

完整 JSON 字符串信息,具体内容参见以下详细信息。

{“callList”:“xxxxx”}
BaseMeAgentIdlong

业务空间 Id,用于区分多业务空间场景下选择指定业务空间,默认为默认业务空间。

123456

请求参数与 JSON 字符串信息

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

jsonStr.callList 属性说明:

属性值类型是否必须描述
voiceFileUrlString录音文件,具体要求详见 API 说明中的录音文件 URL 要求
fileNameString音频文件名称,如 audio.wav;虽不是必填项,但为方便统计,请尽量提供此参数;若不提供,则会从 voiceFileUrl 中获取,比如http://www.aliyun.com/audio.wav,则文件名解析为:audio.wav
autoSplitInteger参见上层对象参数说明;如为空,会采用上层对象对应值。
recognizeRoleDataSetIdLong参见上层对象参数说明;如为空,会采用上层对象对应值。
serviceChannelInteger参见上层对象参数说明;如为空,会采用上层对象对应值。
clientChannelInteger参见上层对象参数说明;如为空,会采用上层对象对应值。
sampleRateInteger参见上层对象参数说明;如为空,会采用上层对象对应值。
callStartTimeLong录音发生的时间,格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒到现在的毫秒数(即毫秒时间戳,例如:1584535485856),若不指定,则会取当前时间。
vocabIdString参见上层对象参数说明;如为空,会采用上层对象对应值。
customerServiceIdLong客服 ID。可从控制台-基础设置-人员管理页面获取,正确填入客服 ID,客服登录控制塔时可以查看与自己关联的录音文件。
customerServiceNameString客服姓名。
skillGroupIdLong技能组 ID。
skillGroupNameString技能组名称。
callTypeInteger呼叫类型,可取值:1:呼出;3:呼入。
calleeString被叫号码,呼出时指的是客户号码,呼入时指的是客服号码。
callerString主叫号码,呼出时指的是客服号码,呼入时指的是客户号码。
callIdString通话 ID,可以是呼叫中心系统中的通话 ID,或者其他可以标识通话的 ID。
businessString业务线名称,属于自定义数据,用于分类统计。
callUuidString全局唯一标识,做幂等(排重)使用,若传入该字段,系统将查询最近两小时内上传的数据中是否存在相同的 callUuid,若存在则本次上传请求将被拒绝。
sessionGroupIdString会话组 ID,通常把同一个客服和同一个客户的会话称之为一个会话组,当传入会话组 ID 后,可在会话组结果页查看会话组维度的质检结果。(仅新版智能对话分析适用)
customerIdString客户 ID。(仅新版智能对话分析适用)
customerNameString客户姓名。(仅新版智能对话分析适用)
schemeTaskConfigIdString手动指定的质检任务 ID(手动指定后则会使用指定的质检任务进行质检) 。(仅新版智能对话分析适用)
remark1String自定义数据 1,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark2String自定义数据 2,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark3String自定义数据 3,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark4String自定义数据 4,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark5Long自定义数据 5,可以存放与您业务相关的自定义字段,格式为有符号的 long 型。
remark6String自定义数据 6,可以存放与您业务相关的自定义字段,最大长度为 1024 字符。
remark7String自定义数据 7,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark8String自定义数据 8,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark9String自定义数据 9,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark10String自定义数据 10,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark11String自定义数据 11,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark12String自定义数据 12,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark13String自定义数据 13,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark14Long自定义数据 14,可以存放与您业务相关的自定义字段,格式为有符号的 long 型。
remark15Long自定义数据 15,可以存放与您业务相关的自定义字段,格式为有符号的 long 型。
remark16String自定义数据 16,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark17String自定义数据 17,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark18String自定义数据 18,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark19String自定义数据 19,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark20String自定义数据 20,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark21String自定义数据 21,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark22String自定义数据 22,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark23String自定义数据 23,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark24String自定义数据 24,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
remark25String自定义数据 25,可以存放与您业务相关的自定义字段,最大长度为 64 字符。
jsonParamStrString更多自定义字段,格式为 JSON 字符串,key 为字段名称,value 为字段内容,示例:{"客户等级":3,"渠道":"官网"}。
complainBoolean是否客诉,用于原因分析模块,该字段若为 true,则将归类到客诉原因分析数据中进行分析。
unsolvedBoolean是否未解决,用于原因分析模块,该字段若为 true,则将归类到未解决原因分析数据中进行分析。

回调参数说明

假设调用方传入的回调地址是:http://aliyun.com/callback,那么回调时的完整 URL 为http://aliyun.com/callback?taskId=xxx&timestamp=xxx&aliUid=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 = "xxx";
    String aliUid = "xxx";
    // 将 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

返回结果

Codestring

结果代码,200 表示成功,若为别的值则表示失败,调用方可根据此字段判断失败原因。

200
Messagestring

出错时表示出错详情,成功时为 successful。

successful
Datastring

任务 ID,在获取任务结果时使用。

76DB5D8C-5BD9-42A7-B527-5AF3A5***
RequestIdstring

请求 ID,请求唯一标识。

76DB5D8C-5BD9-42A7-B527-5AF3A5F8***
Successboolean

请求是否成功,调用方可根据此字段来判断请求是否成功:true 表示成功;false/null 表示失败。

true

示例

正常返回示例

JSON格式

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

错误码

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

变更历史

变更时间变更内容概要操作
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
2023-08-01API 内部配置变更,不影响调用看变更集
变更项变更内容
API 内部配置变更,不影响调用
  • 本页导读 (0)
文档反馈