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

上传离线语音质检数据（录音会话文件）：适用于热线坐席场景。场景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对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
sca:UploadAudioData	create	全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值
JsonStr	string	是	完整 JSON 字符串信息，具体内容参见以下详细信息。	{“callList”:“xxxxx”}
BaseMeAgentId	long	否	业务空间 Id，用于区分多业务空间场景下选择指定业务空间，默认为默认业务空间。	123456

请求参数与 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，"渠道"："官网"}。

回调参数说明

假设调用方传入的回调地址是：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	返回结果
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
}

错误码

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

变更历史

变更时间	变更内容概要	操作
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情
2023-08-01	API 内部配置变更，不影响调用	查看变更详情