# 使用依图语音审核 (/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 中获取录制文件上传的状态和录制文件的信息。