# 使用网易易盾音频审核 (/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"` | 子模块状态异常。 |