使用数美语音审核
本文介绍如何在你的项目中使用数美语音审核服务。
技术原理
通过声网云端录制提供的 RESTful API，你可以对声网频道内的音频流使用第三方语音审核服务。当频道内有用户发送音频流时，审核结果会由第三方直接返回到你的服务器。
对单个频道进行语音审核的流程如下：
- 调用
/acquire接口获取语音审核资源。 - 调用
/start接口开启语音审核任务，并且选择一种审核模式：- 单流模式：分开审核频道内每个 UID 的音频流。
- 合流模式：将频道内所有（或指定）UID 的音频流混合为一路流后进行审核。
- （可选）调用
/query接口查询该审核任务的状态。 - （可选）调用
/update接口更新在频道内订阅的音频流。 - 调用
/stop停止审核任务，释放审核资源。
前提条件
开通语音审核服务
-
注册声网开发者账号，创建项目并获取声网 App ID 和 RTC 临时 Token。详情请参考开通服务。
-
注意
第三方语音审核服务依赖于声网云端录制服务，除了第三方语音审核服务费用，还会产生声网云端录制费用。计费方式详见云端录制计费说明。
-
联系声网技术支持，提供以下信息：
- 公司全称
- 注册声网开发者账户所使用的邮箱和电话
- QPS（每秒查询率）
- 最大并发路数
- 审核内容
成功开通语音审核服务后，声网会向你提供第三方相关的权限信息（如 appId、accessKey 等），后续调用接口时需要传入。
通过 Basic HTTP 认证
语音审核服务要求 Basic HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入 Authorization字段。关于如何生成该字段的值，请参考 HTTP 基本认证。
调用流程
本节介绍使用数美语音审核服务的基本流程。详细的 RESTful API 参数解释参见语音审核 API 参考。
1. 获取审核资源
在开始审核前，必须先调用 /acquire 接口获取审核资源。
例如，你可以使用命令行工具发送以下命令：
# 将 {appid} 替换为你的声网 App ID
curl --location --request POST 'https://api.agora.io/v1/apps/{appid}/cloud_recording/acquire' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
# 将 <YourChannelName> 替换为需要审核的频道名称
# 将 <YourInspectUID> 替换为审核服务的 UID（审核服务相当于频道中一个不发流的客户端）
--data-raw '{
"cname": "<YourChannelName>",
"uid": "<YourInspectUID>",
"clientRequest": {}
}'
设置 uid 参数时需要注意：
- 审核服务相当于频道中一个不发流的客户端。请求包体中的
uid参数用于标识这个不发流的客户端，不可与频道内的任何已有 UID 重复。例如，如果频道内已有两个用户，UID 分别为 123 和 456，则该请求包体中的uid不可为"123"或"456"。 - 审核服务不支持 String 用户 ID（User Account）。请确保频道内所有用户均使用整型 UID。
uid参数的字符串内容也必须为整型。
调用该接口成功后，你会在响应包体中得到一个审核资源 ID（resourceId）。审核资源 ID 的时效为 5 分钟，你需要在 5 分钟内开启审核任务。
2. 开启审核任务
获取审核资源后，在 5 分钟内调用 /start 接口开启审核任务，此时审核服务作为一个不发流的客户端加入频道。一个审核资源 ID 只能开启一个审核任务。
开启审核任务时，你需要选择审核模式：
- 单流模式：分开审核频道内每个 UID 的音频流。单流模式适用于需要精准审核的场景。
- 合流模式：将频道内所有（或指定）UID 的音频流混合为一路流后进行审核。合流模式的审核效率较高，成本较低，但无法准确定位用户。
例如，你可以使用命令行工具发送以下命令，开启一个审核任务：
- 单流模式示例
- 合流模式示例
以下示例中只包含了必填参数，你可以查看语音审核 API 参考来填写各项参数的值。
# 确保在 {mode} 中传入 individual 以使用单流模式
curl --location --request POST 'https://api.agora.io/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start' \
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
"cname": "<YourChannelName>",
"uid": "<YourInspectUID>",
"clientRequest": {
"token": "<YourToken>",
"recordingConfig": {
"channelType": 0,
"streamTypes": 0
},
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "shumei_voice_scan",
"serviceParam": {
"accessKey": "xxxx",
"appId": "xxxx",
"callback": "xxxx",
"type": "xxxx",
"businessType": "xxxx",
"eventId": "xxxx"
},
"streamTypes": 0
}
]
}
}
}'
以下示例中只包含了必填参数，你可以查看语音审核 API 参考来填写各项参数的值。
# 确保在 {mode} 中传入 mix 以使用合流模式
curl --location --request POST 'https://api.agora.io/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start' \
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
"cname": "<YourChannelName>",
"uid": "<YourInspectUID>",
"clientRequest": {
"token": "<YourToken>",
"recordingConfig": {
"channelType": 0,
"streamTypes": 0
},
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "shumei_voice_scan",
"serviceParam": {
"accessKey": "xxxx",
"appId": "xxxx",
"callback": "xxxx",
"type": "xxxx",
"businessType": "xxxx",
"eventId": "xxxx"
},
"streamTypes": 0
}
]
}
}
}'
成功调用 /start 接口后，你会从响应包体中获得一个审核任务 ID（sid），用于标识该审核任务。
3. 接收审核结果
审核结果会以 HTTP 请求的形式直接发送到你在调用 /start 时通过 callback 或 callbackAddr 设置的地址。默认情况下，只有在音频流中检测到违规内容时才会回调审核结果。如果需要全部内容都回调结果，请联系 sales@shengwang.cn 开通。
当频道空闲（无用户）超过预设时间（默认为 30 秒） 后，语音审核会自动停止。
审核结果的回调参数解释详见语音审核 API 参考。
4. 停止审核
审核结束后，调用 /stop 接口停止审核。
例如，你可以使用命令行工具发送以下命令：
# 将 {resourceid} 替换为审核资源标识，即调用 /acquire 接口获取的 resource ID
# 将 {sid} 替换为审核任务标识，即调用 /start 接口获取的 sid
# 将 {mode} 替换为你使用的审核模式，即单流模式（individual）或合流模式（mix）
curl --location --request POST 'https://api.agora.io/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop' \
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
调用 /stop 接口成功后，如果需要再次开始审核，必须重新调用 /acquire 接口请求新的审核资源，即获取一个新的 resourceId。
参考信息
API 参考
语音审核 RESTful API 参数、审核结果回调、错误码和状态码的详细说明，详见语音审核 API 参考。
查询审核状态
审核过程中，你可以调用 /query 接口查询审核状态。
/query 请求仅在审核过程中有效。如果审核启动错误，或审核已结束，调用 /query 将返回 404。
更新音频流订阅
调用 /start 接口后，如果你需要更新语音审核的用户名单，可以调用 /update 接口更新声网频道内的音频流订阅名单。每次调用该接口都会覆盖原来的设置。
录制音频流
如果你需要在审核的同时录制音频流，在调用 /start 时可以通过 recordingFileConfig 配置录制文件格式，通过 storageConfig 配置第三方云存储。具体参数详见开始云端录制 API。
开启录制音频流的功能后，你可以从 /stop 请求的响应包体中获取录制文件上传的状态和录制文件的信息。