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