# 使用网易易盾音频审核 (/zh-CN/realtime-media/content-moderation/build/audio-moderation-api) > 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/content-moderation/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. 在声网控制台的**内容审核**页面填写邮箱等必要信息,并开启音频审核服务。开通步骤详见[开通服务](/zh-CN/realtime-media/content-moderation/enable-service),透传字段和回调地址设计建议详见[配置说明](/zh-CN/realtime-media/content-moderation/build/configuration)。 成功开通语音审核服务后,你可以使用邮箱登陆网易易盾控台,进行审核策略配置,获取审核权限信息(如 `SecretId`、`SecretKey` 等),后续调用接口时需要传入。 ### 通过 Basic HTTP 认证 [#通过-basic-http-认证] 语音审核服务要求 Basic HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入 `Authorization`字段。关于如何生成该字段的值,请参考 [HTTP 基本认证](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/http-basic-auth)。 ## 调用流程 [#调用流程] 本节介绍使用网易易盾音频审核服务的基本流程。详细的 RESTful API 参数解释参见[API 参考](#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 的音频流混合为一路流后进行审核。合流模式的审核效率较高,成本较低,但无法准确定位用户。 例如,你可以使用命令行工具发送以下命令,开启一个审核任务: 单流模式示例 合流模式示例 以下示例中只包含了必填参数,你可以查看[开启审核任务](#start)来填写各项参数的值。 ```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": { "extensionServices": [ { "errorHandlePolicy": "error_abort", "serviceName": "yidun_voice_scan", "serviceParam": { "businessId": "e97a4b755dxxxx909eebd78be6", "callbackUrl": "http://103.229.213.112:8889/paas/yidun", "dataId": "17744xxxx669749", "extension": "{}", "nonce": 1804934882, "roomNo": "YJ", "secretId": "70fdb6d660xxx72a357e009bc", "signature": "377fcfb801xxxx1939af62157244", "signatureMethod": "md5", "timestamp": 1774497460, "version": "v4.1" }, } ] } } }' ``` 以下示例中只包含了必填参数,你可以查看[开启审核任务](#start)来填写各项参数的值。 ```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": { "extensionServices": [ { "errorHandlePolicy": "error_abort", "serviceName": "yidun_voice_scan", "serviceParam": { "businessId": "e97a4b755dxxxx909eebd78be6", "callbackUrl": "http://103.229.213.112:8889/paas/yidun", "dataId": "17744xxxx669749", "extension": "{}", "nonce": 1804934882, "roomNo": "YJ", "secretId": "70fdb6d660xxx72a357e009bc", "signature": "377fcfb801xxxx1939af62157244", "signatureMethod": "md5", "timestamp": 1774497460, "version": "v4.1" }, } ] } } }' ``` :::info[信息] 如果你需要在审核的同时录制音频流,在调用 `/start` 时可以通过 `recordingFileConfig` 配置录制文件格式,通过 `storageConfig` 配置第三方云存储。具体参数详见[开始云端录制 API](/zh-CN/realtime-media/cloud-recording/reference/api-reference)。 开启录制音频流的功能后,你可以从 `/stop` 请求的响应包体中获取录制文件上传的状态和录制文件的信息。 ::: 成功调用 `/start` 接口后,你会从响应包体中获得一个审核任务 ID(`sid`),用于标识该审核任务。 ### 3. 接收审核结果 [#3-接收审核结果] 审核结果会以 HTTP 请求的形式直接发送到你在调用 `/start` 时通过 `callback` 设置的格式,指定回调地址 `callbackUrl` ,详见 `serviceParam`。默认情况下,只有在音频流中检测到违规内容时才会回调审核结果。 :::info[信息] 当频道空闲(无用户)超过预设时间(默认为 30 秒) 后,语音审核会自动停止。 ::: 审核结果的回调参数解释详见[API 参考](#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。 #### 请求结构 [#请求结构] - 仅支持 HTTPS 协议。 - 请求 Header 的 `Content-type` 为 `application/json;charset=utf-8`。 - 请求 Header 的 `Authorization` 字段需要你自行生成,生成方法参考 [HTTP 基本认证](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/http-basic-auth)。 #### 公共参数 [#公共参数] 本节介绍语音审核 RESTful API 的公共参数。 ##### 公共请求参数 [#公共请求参数] 每次请求都需要传入以下参数: | 参数 | 类型 | 描述 | 备注 | | --- | --- | --- | --- | | `appid` | String | 你的[声网 App ID](/zh-CN/realtime-media/content-moderation/enable-service#获取-app-id)。必须使用待审核的频道所对应的 App ID。 | 路径参数 | | `cname` | String | 待审核的频道名。 | Body 参数 | | `uid` | String | 标识音频审核服务(相当于频道内一个不发流的客户端)的用户 ID,例如 `"527841"`。取值范围为 `[1, 2³² - 1]`,不可设置为 `0`,不能与当前频道内的任何用户 ID 重复,且频道内所有用户均需使用整型用户 ID。 | Body 参数 | ##### 公共响应参数 [#公共响应参数] 每次发送请求后,响应 Header 中都会返回[响应状态码](#code)。 #### 配额限制 [#配额限制] 每秒钟的请求数限制(QPS)为 10 次。如需提高此限制,请[联系技术支持](https://ticket.shengwang.cn/)。 ### 获取审核资源 [#获取审核资源] #### 接口原型 [#接口原型] - 请求方法:POST - 请求 URL:`https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/acquire` #### 请求参数 [#请求参数] ##### Body 参数 [#body-参数] 除[公共参数](#公共参数)外,请求 Body 中还需要传入以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `clientRequest` | Object | 客户请求参数,使用音频审核时你需要设置该对象的 `resourceExpiredHour` 字段,用于设置音频审核 RESTful API 的调用时效。 | #### 响应参数 [#响应参数] 响应 Body 中包含以下字段: - `resourceId`:String 类型,审核资源 ID。一个审核资源 ID 只能用于开启一个审核任务。 :::info[信息] - 调用该接口获取的 `resourceId` 时效为 5 分钟,你需要在 5 分钟内使用该 `resourceId` 调用 [`/start`](#start) 接口开启审核任务,如果超时则需要重新获取。 - 如需开启多个审核任务,声网建议你按照先 `/acquire` 后 `/start` 的调用顺序逐个开启,请勿多次调用 `/acquire` 获取多个 `resourceId` 而导致资源过期。 ::: #### 示例 [#示例] **请求行** ```shell POST https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/acquire HTTPS/1.1 ``` **请求 Body** ```json { "clientRequest": { "resourceExpiredHour": 24 }, "cname": "httpClient463224", "uid": "527841" } ``` **响应 Body** ```json { "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG" } ``` ### 开启审核任务 [#开启审核任务] #### 接口原型 [#接口原型-1] - 请求方法:POST - 请求 URL:`https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start` #### 请求参数 [#请求参数-1] ##### 路径参数 [#路径参数] 除[公共参数](#公共参数)外,请求 URL 中还包含以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `resourceid` | String | 通过 `/acquire` 请求获取的审核资源 ID。 | | `mode` | String | 审核模式,支持 `individual`(单流模式)和 `mix`(合流模式)。 | ##### Body 参数 [#body-参数-1] 除[公共参数](#公共参数)外,请求 Body 中还需要传入以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `clientRequest` | Object | 特定的客户请求参数,包含 `token`、`recordingConfig` 和 `extensionServiceConfig` 等字段。 | **recordingConfig 成员如下:** - `channelType`:Number 类型,频道场景。频道场景必须与声网 RTC SDK 的设置一致,否则可能导致问题。 - `0`:(默认)通信场景 - `1`:直播场景 - `streamTypes`:Number 类型,订阅的媒体流类型。**使用语音审核时,你需要将其设置为 `0`,即仅订阅音频。** - `0`:仅订阅音频 - `streamMode`:(选填)String 类型,单流模式下(`mode` 为 `individual`),媒体流的输出模式。 - `default`:默认模式。审核过程中音频转码。 - `decryptionMode`:(选填)Number 类型,解密方案。如果频道设置了加密,该参数必须设置。解密方式必须与频道设置的加密方式一致。 - `0`:(默认)不加密。 - `1`:AES_128_XTS 加密模式。128 位 AES 加密,XTS 模式。 - `2`:AES_128_ECB 加密模式。128 位 AES 加密,ECB 模式。 - `3`:AES_256_XTS 加密模式。256 位 AES 加密,XTS 模式。 - `4`:SM4_128_ECB 加密模式。128 位 SM4 加密,ECB 模式。 - `5`:AES_128_GCM 加密模式。128 位 AES 加密,GCM 模式。 - `6`:AES_256_GCM 加密模式。256 位 AES 加密,GCM 模式。 - `7`:AES_128_GCM2 加密模式。128 位 AES 加密,GCM 模式。 相比于 AES_128_GCM 加密模式,AES_128_GCM2 加密模式安全性更高且需要设置密钥和盐。 - `8`:AES_256_GCM2 加密模式。256 位 AES 加密,GCM 模式。相比于 AES_256_GCM 加密模式,AES_256_GCM2 加密模式安全性更高且需要设置密钥和盐。 - `secret`:(选填)String 类型,启用解密模式后,设置的解密密码。 - `salt`:(选填)Base64 编码、32 位字节。启用解密模式后,设置解密的[盐](https://en.wikipedia.org/wiki/Salt_(cryptography))。如果 `decryptionMode` 为 7 或 8,则需要设置该值。 - `audioProfile`:(选填)Number 类型,设置输出音频的采样率,码率,编码模式和声道数。**目前仅适用于合流模式。** - `0`:(默认)48 kHz 采样率,音乐编码,单声道,编码码率约 48 Kbps - `1`:48 kHz 采样率,音乐编码,单声道,编码码率约 128 Kbps - `2`:48 kHz 采样率,音乐编码,双声道,编码码率约 192 Kbps - `maxIdleTime`:(选填)Number 类型,最长空闲频道时间。默认值为 30 秒,该值需大于等于 5,且小于等于 (2³² - 1)。如果频道内无用户的状态持续超过该时间,审核服务会自动退出。 - 通信场景下,如果频道内有用户,但用户没有发流,不算作无用户状态。 - 直播场景下,如果频道内有观众但无主播,一旦无主播的状态超过 `maxIdleTime`,审核服务会自动退出。 - `subscribeAudioUids`:(选填)JSONArray 类型,由 UID 组成的数组,指定订阅哪几个 UID 的音频流。数组长度不得超过 32,不推荐使用空数组。 - `unSubscribeAudioUids`: (选填)JSONArray 类型,由 UID 组成的数组,指定不订阅哪几个 UID 的音频流。审核服务会订阅频道内除指定 UID 外所有 UID 的音频流。数组长度不得超过 32,不推荐使用空数组。`subscribeAudioUids` 和 `unSubscribeAudioUids` 不能同时设置。 - `subscribeUidGroup`: (选填)Number 类型,预估的订阅人数峰值。**在单流模式下,为必填参数**。举例来说,如果 `subscribeAudioUids` 为 `["100","101","102"]`,则订阅人数为 3 人,该参数需要设置为 `1`。 - `0`: 1 到 2 人 - `1`: 3 到 7 人 - `2`: 8 到 12 人 - `3`: 13 到 17 人 **extensionServiceConfig 成员如下:** - `errorHandlePolicy`:(选填)String 类型,错误处理策略。目前仅可设为: - `"error_abort"`:(默认)当扩展服务发生错误后,订阅等其他服务均停止。 - `apiVersion`:(选填)String 类型,语音审核 RESTful API 的版本号,默认为 `"v1"`。 - `extensionServices`:JSONArray 类型,由每个扩展服务的设置组成的数组。使用语音审核时需要设置以下参数: - `serviceName`:String 类型,扩展服务的名称。可设为: - `yidun_voice_scan`:网易易盾音频审核。 - `errorHandlePolicy`:(选填)String 类型。错误处理策略。目前仅可设为: - `"error_abort"`:(默认)当扩展服务发生错误后,订阅等其他服务均停止。 - `streamTypes`:Number 类型,要审核的媒体流类型。使用语音审核时,你需要将其设置为 `0`,即仅审核音频。 - `0`:仅订阅音频 - `1`:仅订阅视频 - `2`:(默认)订阅音频和视频 - `serviceParam`:JSON Object 类型,扩展服务的具体参数设置。当使用语音审核时,你需要设置以下字段: 网易易盾 | 参数名称 | 类型 | 是否必选 | 最大长度 | 描述 | | --- | --- | --- | --- | --- | | secretId | String | 是 | 32 | 产品密钥 id,由易盾内容安全服务系统生成,可在智能审核后台-产品业务管理中获取,如有疑问可咨询策略经理引导获取,产品标识 | | businessId | String | 是 | 32 | 业务 id,由易盾内容安全服务系统生成,可在智能审核后台-产品业务管理中获取,如有疑问可咨询策略经理引导获取,业务标识 | | timestamp | Number | 是 | 13 | 请求当前 UNIX 时间戳,请注意服务器时间是否同步 | | nonce | Number | 是 | 11 | 随机整数,与 timestamp 联合起来,用于防止重放攻击 | | signatureMethod | String | 否 | 指定传参 | 指定签名算法,目前只支持 MD5 | | signature | String | 是 | 32 | 请求签名,用来验证此次请求的合法性。签名生成算法如下:1. 对 serviceParam 中的所有请求参数(不包括 signature 参数),按照参数名 ASCII 码表升序排序;2. 将排序好的参数名和参数值拼接成字符串,格式为:key1+value1+key2+value2…;3. 将 secretKey 拼接到上一步字符串末尾;4. 对拼接好的字符串使用 UTF-8 编码,进行 MD5 摘要计算,得到 32 位十六进制字符串即为 signature 值 | | version | String | 是 | 4 | 接口版本号,值为 v4.1 | | dataId | String | 是 | 128 | 上传数据唯一标识,能够根据该值定位到该条数据,如对数据结果有异议,可以发送该值给客户经理查询 | | roomNo | String | 是 | 128 | 主播房间号 | | callbackUrl | String | 是 | 512 | 离线结果回调通知到客户的 URL。主动回调数据接口超时时间设置为 2s,为了保证顺利接收数据,需保证接收接口性能稳定并且保证幂等性 | | callback | String | 否 | 1024 | 数据回调参数,调用方根据业务情况自行设计,当调用 callback 接口获取直播音频结果时,该接口会原样返回该字段,详细见直播音频离线检测结果获取。作为数据处理标识,因此该字段应该设计为能唯一定位到该次请求的数据结构,如对用户的昵称进行检测,dataId 可设为用户标识(用户 ID),用户修改多次,每次请求数据的 dataId 可能一致,但是 callback 参数可以设计成定位该次请求的数据结构,比如 callback 字段设计成 JSON,包含 dataId 和请求的时间戳等信息,当然如果不想做区分,也可以直接把 callback 设置成 dataId 的值 | | extension | String | 否 | 30000 | 自定义扩展参数,JSON 字符串格式。如:`{"keyName1":"value1","keyName2":"value2"}` | 回调结果中包含 `clientRequest` 信息,其中包含 `cname` 和 `uid` 字段,可用于与审核频道以及发流端进行关联。 #### 响应参数 [#响应参数-1] 响应 Body 中包含以下字段: - `cname`:String 类型,待审核的频道名。 - `uid`:String 类型,字符串内容为审核服务在 RTC 频道内使用的 UID,用于标识该审核服务。 - `resourceId`:String 类型,该审核任务使用的审核资源 ID。 - `sid`:String 类型,该审核任务的唯一标识。 #### 示例 [#示例-1] **请求行** ```shell POST https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start HTTPS/1.1 ``` **请求 Body** 以单流模式为例: ```json tab="网易易盾示例" tabGroup="vendor" { "clientRequest": { "appsCollection": { "combinationPolicy": "default" }, "extensionServiceConfig": { "extensionServices": [ { "errorHandlePolicy": "error_abort", "serviceName": "yidun_voice_scan", "serviceParam": { "businessId": "e97a4b755df46d25078a909eebd78be6", "callbackUrl": "http://103.229.213.112:8889/paas/yidun", "dataId": "1774497460376669749", "extension": "{}", "nonce": 1804934882, "roomNo": "YJ", "secretId": "70fdb6d660d522764a8f72a357e009bc", "signature": "377fcfb801114e150b1939af62157244", "signatureMethod": "md5", "timestamp": 1774497460, "version": "v4.1" } } ] }, "recordingConfig": { "channelType": 1, "maxIdleTime": 100, "streamMode": "default", "streamTypes": 0, "subscribeAudioUids": [ "#allstream#" ], "subscribeUidGroup": 0 } }, "cname": "xxx", "uid": "1774497460" } ``` **响应 Body** ```json { "cname": "httpClient463224", "uid": "527841", "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG", "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a" } ``` ### 查询审核状态 [#查询审核状态] 审核过程中,你可以调用 `/query` 接口查询审核状态。 `/query` 请求仅在审核过程中有效。如果审核启动错误,或审核已结束,调用 `/query` 将返回 404。 #### 接口原型 [#接口原型-2] - 请求方法:GET - 请求 URL:`https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/query` #### 请求参数 [#请求参数-2] ##### 路径参数 [#路径参数-1] 除[公共参数](#公共参数)外,请求 URL 中还包含以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `resourceid` | String | 通过 `/acquire` 请求获取的审核资源 ID。 | | `sid` | String | 通过 `/start` 请求获取的审核任务 ID。 | | `mode` | String | 审核模式,支持 `individual`(单流模式)和 `mix`(合流模式)。 | #### 响应参数 [#响应参数-2] 响应 Body 中包含以下字段: - `resourceId`:String 类型,语音审核的审核资源 ID。 - `sid`:String 类型,通过 `/start` 请求获取的审核任务 ID。 - `serverResponse`:JSON Object 类型,服务器返回的具体信息。 - `subServiceStatus`:JSON Object 类型,子模块的服务状态。 - `recordingService`:String 类型,订阅模块的状态,具体取值详见[服务状态](#status)。 - `mediaDistributeService`:String 类型,媒体分发模块的状态,具体取值详见[服务状态](#status)。该模块用于管理扩展服务,控制媒体流向各扩展服务的分发。 - `extensionServiceState`:JSONArray 类型,由各个扩展服务的当前状态组成的数组。 - `serviceName`:String 类型,扩展服务的名称: - `yidun_voice_scan`:网易易盾音频审核。 - `streamState`:JSONArray 类型,该扩展服务的状态。当选择网易易盾音频审核时,返回以下参数: - `uid`:Number 类型,用户 UID,表示审核的是哪个用户的媒体流。合流模式下,`uid` 总为 `0`。 - `streamType`:String 类型,审核的内容类型。`"audio"` 指纯音频。 - `status`:审核的状态。 - `"inProgress"`:审核正在进行中。 - `"failed"`:审核发生错误。 #### 示例 [#示例-2] **请求行** ```shell GET https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/query HTTPS/1.1 ``` **响应 Body** 以单流模式为例: ```json { "resourceId": "Etkl6g-zSB7EpP-Da1zN67U-tt4soO0PZ0SW6nl1EGu8MSTU96ioRjKOO-3PgKb-TBNM_pEudbZ3Udy2wxOZRNgb3dpH__glt5_D-6ikPjkde3CfHeZtsa5fffoZjnfk865Q271HRmP--p8RZm0A-7S39HFBJIPtugfjyzocNzTTw2_xttK97rKU-B1wl1uurKmiRj4453L7ETNLeM6NKskNqYZ0holdfQs3ijC7WNNgdlWVeYTBKT83G6jC99eXKBnBqs-6Lu1_C9S9qprRIE7js-xgLLX3TIEwi69milO8b-I958yKyn6fLX3PNSNshZZUVUfIlqMPYbe7NtRXC-HRY2YM3xq0K-4-wPVPfCA", "sid": "e36fb8add64933c71c315784b93ca5cb", "serverResponse": { "extensionServiceState": [ { "serviceName": "yidun_voice_scan", "streamState": [ { "status": "inProgress", "streamType": "audio", "uid": "0" } ] } ], "subServiceStatus": { "recordingService": "serviceInProgress", "mediaDistributeService": "serviceInProgress" } } } ``` ### 更新音频流订阅 [#更新音频流订阅] 调用 `/start` 接口后,如果你需要更新语音审核的用户名单,可以调用 `/update` 接口更新声网频道内的音频流订阅名单。每次调用该接口都会覆盖原来的设置。 #### 接口原型 [#接口原型-3] - 请求方法:POST - 请求 URL:`https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update` #### 请求参数 [#请求参数-3] ##### 路径参数 [#路径参数-2] 除[公共参数](#公共参数)外,请求 URL 中还包含以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `resourceid` | String | 通过 `/acquire` 请求获取的审核资源 ID。 | | `sid` | String | 通过 `/start` 请求获取的审核任务 ID。 | | `mode` | String | 审核模式,支持 `individual`(单流模式)和 `mix`(合流模式)。 | ##### Body 参数 [#body-参数-2] 除[公共参数](#公共参数)外,请求 Body 中还需要传入以下参数: | 参数 | 类型 | 描述 | | :-------------- | :--- | :----------------------------------------------------------- | | `clientRequest` | Object | 客户请求参数,对于该请求仅包含 `streamSubscribe` 字段。该字段为 JSON Object 类型,用于更新音频流的订阅名单。 | `streamSubscribe` 包含以下成员: - `audioUidList`:(选填)JSON Object 类型。音频订阅名单。如果 `recordingConfig` 中的 `streamTypes` 为 `1` (只订阅视频),设置该参数会报错。 - `subscribeAudioUids`:(选填)JSONArray 类型,由 UID 组成的数组,指定订阅哪几个 UID 的音频流。数组长度不得超过 32,数组不可为空。详见[订阅名单设置](/zh-CN/realtime-media/cloud-recording/reference/api-reference#订阅名单设置)。 - `unSubscribeAudioUids`: (选填)JSONArray 类型,由 UID 组成的数组,指定不订阅哪几个 UID 的音频流。审核服务会订阅频道内除指定 UID 外所有 UID 的音频流。数组长度不得超过 32,数组不可为空。详见[订阅名单设置](/zh-CN/realtime-media/cloud-recording/reference/api-reference#订阅名单设置)。 #### 响应参数 [#响应参数-3] 响应 Body 中包含以下字段: - `resourceId`:String 类型,语音审核的审核资源 ID。 - `sid`:String 类型,通过 `/start` 请求获取的审核任务 ID。 #### 示例 [#示例-3] **请求行** ```shell POST https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update HTTPS/1.1 ``` **请求 Body** ```json { "uid": "527841", "cname": "httpClient463224", "clientRequest": { "streamSubscribe": { "audioUidList": { "subscribeAudioUids": ["#allstream#"] } } } } ``` **响应 Body** ```json { "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG", "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a" } ``` ### 停止审核 [#停止审核] #### 接口原型 [#接口原型-4] - 请求方法:POST - 请求 URL:`https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop` #### 请求参数 [#请求参数-4] ##### 路径参数 [#路径参数-3] 除[公共参数](#公共参数)外,请求 URL 中还包含以下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `resourceid` | String | 通过 `/acquire` 请求获取的审核资源 ID。 | | `sid` | String | 通过 `/start` 请求获取的审核任务 ID。 | | `mode` | String | 审核模式,支持 `individual`(单流模式)和 `mix`(合流模式)。 | ##### Body 参数 [#body-参数-3] 除[公共参数](#公共参数)外,请求 Body 中还需要传入以下参数: | 参数 | 类型 | 描述 | | :-------------- | :--- | :----------------------------------------------------------- | | `clientRequest` | Object | 特定的客户请求参数,对于该接口无需填入任何内容,为一个空的 JSON Object。 | #### 响应参数 [#响应参数-4] 响应 Body 中包含以下字段: - `resourceId`:String 类型,语音审核使用的审核资源 ID。 - `sid`:String 类型,审核任务 ID。成功开始语音审核后,你会得到一个 `sid` , 是该审核任务的唯一标识。 #### 示例 [#示例-4] **请求行** ```shell POST https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop HTTPS/1.1 ``` **请求 Body** ```json { "cname": "httpClient463224", "uid": "527841", "clientRequest": {} } ``` **响应 Body** ```json { "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG" } ``` ### 审核结果回调 [#审核结果回调] 语音审核结果会以 HTTP 请求的形式直接发送到你在 `extensionServiceConfig` 中设置的回调地址。回调参数详见[网易易盾音频审核接口文档](https://support.dun.163.com/documents/588434426518708224?docId=600817330300723200)。 回调结果中包含 `clientRequest` 信息,其中包含 `cname` 和 `uid` 字段,可用于关联审核频道与发流端。 ### 错误码和状态码 [#错误码和状态码] 本文仅列出使用云端录制 RESTful API 过程中常见的错误码和状态码。如果遇到其他错误,请[联系技术支持](https://ticket.shengwang.cn/)。 #### 错误码 [#错误码] - `2`:参数不合法,请确保参数类型正确、大小写正确、必填的参数均已填写。 - `7`:审核已经在进行中 ,请勿用同一个 `resourceId` 重复 `/start` 请求。 - `8`:HTTP 请求 Header 字段错误,有以下几种情况: - `Content-type` 错误,请确保 `Content-type` 为 `application/json;charset=utf-8`。 - 请求 URL 中缺少 `cloud_recording` 字段。 - 使用了错误的 HTTP 方法。 - 请求 Body 不是合法的 JSON 格式。 - `49`:使用同一个审核资源 ID(`resourceId`) 和审核任务 ID(`sid`)重复 `/stop` 请求。 - `53`:审核已经在进行中。当采用相同参数再次调用 `/acquire` 获得新的 `resourceId` 并用于 `/start` 请求时,会发生该错误。如需发起多路审核,需要在 `/acquire` 方法中填入不同的 UID。 - `62`:调用 `/acquire` 请求时,如果出现该错误,表示你填入的 App ID 没有开通第三方语音审核服务,或者没有开通云录制服务。 - `65`:多为网络抖动引起。当调用 `/start` 收到该错误码时,需要使用同一 Resource ID 再次调用 `start`。建议使用退避策略重试两次,如第一次等待 3 秒后重试、第二次等待 6 秒后重试。 - `109`:加入 RTC 频道的鉴权 Token 过期,你需要获取新的 Token。 - `110`:加入 RTC 频道的鉴权 Token 错误,你需要确认你是否获取了正确的 Token。 - `432`:请求参数错误。请求参数不合法,或请求中的 App ID,频道名或用户 ID 与 Resource ID 不匹配。 - `433`:Resource ID 过期。获得 `resourceId` 后必须在 5 分钟内开始审核。请重新调用 `/acquire` 获取新的 `resourceId`。 - `435`:频道内没有用户加入,无审核对象。 - `501`:审核正在退出。该错误可能在调用了 `/stop` 接口后再调用 `/query` 时发生。 - `1001`:Resource ID 解密失败。请重新调用 `/acquire` 获取新的 Resource ID。 - `1003`:声网 App ID 或者审核任务 ID(`sid`)与审核资源 ID(`resourceId`) 不匹配。请确保在一个审核周期内声网 App ID、 `resourceId`、`sid` 一一对应。 - `1013`:频道名不合法。频道名必须为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符): - 26 个小写英文字母 a-z - 26 个大写英文字母 A-Z - 10 个数字 0-9 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "\_", "{", "}", "|", "~", "," - `"invalid appid"`:无效的声网 App ID。请确保声网 App ID 填写正确。如果你已经确认 App ID 填写正确,但仍出现该错误,请[联系技术支持](https://ticket.shengwang.cn/)。 - `"no Route matched with those values"`:该错误可能由 HTTP 方法填写错误导致,例如将 `GET` 方法填写为 `POST`;也可能由请求 URL 填写错误导致。 - `"Invalid authentication credentials"`:该错误可能由以下原因导致。如果你已经排除以下原因,但仍出现该错误,请[联系技术支持](https://ticket.shengwang.cn/)。 - 客户 ID 或客户密钥填写错误。 - App ID 没有开通第三方语音审核服务或开通云端录制服务。 - 请求 Header 的认证信息有误,如 `Authorization` 字段的值 `Basic ` 缺少 `Basic`。 - 请求 Header 的格式不正确,如 `Content-type` 字段的值 `application/json;charset=utf-8` 大小写不正确或包含空格。 #### 响应状态码 [#响应状态码] | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 录制已经在进行中 ,请勿用同一个 Resource ID 重复 `start` 请求。 | | `206` | 整个录制过程中没有用户发流,或部分录制文件没有上传到第三方云存储,或录制进程还未结束。 | | `400` | 请求的语法错误(如参数错误)。如果你填入的声网 App ID 没有开通第三方语音审核服务,也会返回 400。 | | `401` | 未经授权的(客户 ID/客户密钥匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | #### 服务状态 [#服务状态] | 状态 | 描述 | | :------------------------ | :----------------------------------------------------------- | | `"serviceIdle"` | 子模块服务未开始。 | | `"serviceStarted"` | 子模块服务已开始。 | | `"serviceReady"` | 子模块服务已就绪。 | | `"serviceInProgress"` | 子模块服务正在进行中。 | | `"serviceCompleted"` | 审核内容已全部上传至语音审核。 | | `"servicePartialCompleted"` | 审核内容部分上传至语音审核。 | | `"serviceValidationFailed"` | 语音审核验证失败。例如 `extensionServiceConfig` 中 `apiData` 填写错误。 | | `"serviceAbnormal"` | 子模块状态异常。 |