# 使用依图语音审核 (/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，你可以对声网频道内的音频流使用第三方语音审核服务。当频道内有用户发送音频流时，审核结果会由第三方直接返回到你的服务器。

<DocsImage alt="语音审核流程" src="https://web-cdn.agora.io/docs-files/1669343507453" displayWidth="80%" />

对单个频道进行语音审核的流程如下：

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' \
# 将 <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. 开启审核任务 [#2-开启审核任务]

获取审核资源后，在 5 分钟内调用 `/start` 接口开启审核任务，此时审核服务作为一个不发流的客户端加入频道。一个审核资源 ID 只能开启一个审核任务。

开启审核任务时，你需要选择审核模式：

- 单流模式：分开审核频道内每个 UID 的音频流。单流模式适用于需要精准审核的场景。
- 合流模式：将频道内所有（或指定）UID 的音频流混合为一路流后进行审核。合流模式的审核效率较高，成本较低，但无法准确定位用户。

例如，你可以使用命令行工具发送以下命令，开启一个审核任务：

<Tabs defaultValue="individual" groupId="recording-mode" persist>
<TabsList>
  <TabsTrigger value="individual">单流模式示例</TabsTrigger>
  <TabsTrigger value="composite">合流模式示例</TabsTrigger>
</TabsList>

<TabsContent value="individual">

以下示例中只包含了必填参数，你可以查看[语音审核 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 <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": "yitu_voice_async_scan",
                    "serviceParam": {
                        "apiData": {
                            "accessKey": "xxxx",
                            "bizType": "xxxx",
                            "callbackSeed": "xxxx",
                            "secretKey": "xxxx"
                        },
                        "callbackAddr": "http://xxxx"
                    },
                    "streamTypes": 0
                }
            ]
        }
    }
}'
```

</TabsContent>

<TabsContent value="composite">

以下示例中只包含了必填参数，你可以查看[语音审核 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 <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": "yitu_voice_async_scan",
                    "serviceParam": {
                        "apiData": {
                            "accessKey": "xxxx",
                            "bizType": "xxxx",
                            "callbackSeed": "xxxx",
                            "secretKey": "xxxx"
                        },
                        "callbackAddr": "http://xxxx"
                    },
                    "streamTypes": 0
                }
            ]
        }
    }
}'
```

</TabsContent>
</Tabs>

成功调用 `/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 <Authorization>' \
--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 中获取录制文件上传的状态和录制文件的信息。