使用智能语音审核服务,你需要支付声网收取的录制费用以及第三方语音审核服务费用。录制计费方式详见云端录制计费说明,第三方语音审核服务计费方式请咨询 sales@agora.io。
本文介绍使用 RESTful 开始智能语音审核、查询智能语音审核状态以及结束智能语音审核。
在你使用声网实时音视频服务时,你可以使用第三方智能语音审核对音频内容进行多样化场景检测,帮助你对内容进行管控,规避内容违规风险。
娱乐直播平台的用户数日益增长,用户传播的内容可能存在各种不可控的风险因素,例如色情、暴恐和涉政等。随着政府监管的日趋严格,娱乐直播平台为了对内容进行管控,需要投入大量人力进行内容审核。第三方智能语音审核可对音频内容进行有效的判别和筛选,大大降低人力投入。
第三方智能语音审核检测的业务类型包括:
检测语音中的违规或不良内容,具体包括以下场景:
当你调用声网 RESTful API 发起智能语音审核时,声网服务器会获取频道内的音频流,并将音频流推送到第三方服务器进行审核,最后将审核结果以 HTTP 请求的形式发送到你指定的服务器地址。同时,声网服务器可以将频道内的音频流录制为音频文件,并上传至第三方云存储。
第一次使用智能语音审核服务之前,你需要联系声网技术支持开通语音审核服务,并获取相关参数。
所有的请求都发送给域名:api.agora.io
。仅支持 HTTPS 协议。
所有的请求 URL 和请求包体内容都是区分大小写的。
声网 RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入 Authorization
字段。关于如何生成该字段的值,请参考 HTTP 基本认证。
要对频道内的音频进行实时审核,你需要调用智能语音审核 RESTful API,发送 HTTPS 请求。智能语音审核会将审核结果以 HTTP 请求的形式发送到你指定的地址。
下图为实现音频审核需要调用的 API 时序图。
一般进行审核的步骤如下:
acquire
请求获取一个 resource ID 用于开启智能语音审核。start
开始审核。stop
停止审核。在整个过程中可以通过 query
请求查询审核的状态。
在开始审核之前,你需要调用该方法获取一个 resource ID,用于开启智能语音审核。
一个 resource ID 只能用于一次审核。
每个 App ID 每秒钟的请求数限制为 10 次。如需提高此限制,请联系技术支持。
调用该方法成功后,你可以从 HTTP 响应包体中的 resourceId
字段得到一个 resource ID。这个 resource ID 的时效为 5 分钟,你需要在 5 分钟内用该 resource ID 调用 start
方法,超时需重新调用 acquire
申请。在审核中该资源一直有效,直到审核结束。
该 API 需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appid |
String | 你的项目使用的 App ID。必须使用和待审核的频道相同的 App ID。 |
该 API 需要在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
cname |
String | 待审核的频道名。 |
uid |
String | 字符串内容为智能语音审核使用的 UID,用于标识该审核服务,例如"527841" 。需满足以下条件:
|
clientRequest |
JSON | 客户请求参数,包含 resourceExpiredHour 字段:resourceExpiredHour 为 Number 类型,单位为小时,用于设置智能语音审核 RESTful API 的调用时效,从成功开启审核并获得 sid (审核 ID)后开始计算。超时后,你将无法调用 query 和 stop 方法。resourceExpiredHour 需大于等于 1 , 且小于等于 720 ,默认值为 72 。 |
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire
Content-type
为 application/json;charset=utf-8
Authorization
为 Basic authorization,生成方法请参考 RESTful API 认证。{
"clientRequest": {
"resourceExpiredHour": 24
},
"cname": "httpClient463224",
"uid": "527841"
}
"Code": 200,
"Body":
{
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
:Number 类型,详见响应状态码。resourceId
:String 类型,智能语音审核的 resource ID,使用这个 resource ID 可以开始一段审核。获取 resource ID 后,调用该方法开始审核。
每个 APP ID 每秒钟的请求数限制为 10 次。如需提高此限制,请联系技术支持。
该 API 需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appid |
String | 你的项目使用的 App ID。必须使用和待审核的频道相同的 App ID。 |
resourceid |
String | 通过 acquire 请求获取的 resource ID。 |
mode |
String | 审核模式,支持以下模式:individual ):分开审核频道内每个 UID 的音频流。mix): 将频道内所有(或指定)UID 的音频流混合为一路流后进行审核。 |
该 API 需要在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
cname |
String | 待审核的频道名。 |
uid |
String | 字符串内容为智能语音审核使用的 UID,用于标识该审核服务,需要和你在 acquire 请求中输入的 uid 相同。 |
clientRequest |
JSON | 特定的客户请求参数,对于该请求包含以下参数:token :String 类型,用于鉴权的动态密钥。如果你的项目已启用 App 证书,则务必在该参数中传入你项目的动态密钥。详见使用 Token 鉴权。recordingConfig :JSON Object,订阅的详细设置。审核服务会对你订阅的内容进行审核。extensionServiceConfig :JSON Object,扩展服务的设置,包括数美或依图智能语音审核的详细设置。 |
订阅设置
recordingConfig
是一个用于设置订阅选项的 JSON Object。智能语音审核会对你设置的订阅内容进行审核。recordingConfig
包含以下字段:
channelType
:Number 类型,频道场景。频道场景必须与声网 RTC SDK 的设置一致,否则可能导致问题。
0
:(默认)通信场景1
:直播场景streamTypes
:Number 类型,订阅的媒体流类型。使用智能语音审核时,你需要将其设置为 0
,即仅订阅音频。
0
:仅订阅音频1
:仅订阅视频2
:(默认)订阅音频和视频streamMode
:(选填)String 类型,单流模式下(mode
为 individual
),媒体流的输出模式。
default
:默认模式。审核过程中音频转码。original
:原始编码模式。仅订阅音频时(streamTypes
为 0
)时该参数生效,审核过程中音频不转码。decryptionMode
:(选填)Number 类型,解密方案。如果频道设置了加密,该参数必须设置。解密方式必须与频道设置的加密方式一致。
secret
:(选填)String 类型,启用解密模式后,设置的解密密码。
audioProfile
:(选填)Number 类型,设置输出音频的采样率,码率,编码模式和声道数。目前仅适用于合流模式。
0
:(默认)48 kHz 采样率,音乐编码,单声道,编码码率约 48 Kbps1
:48 kHz 采样率,音乐编码,单声道,编码码率约 128 Kbps2
:48 kHz 采样率,音乐编码,双声道,编码码率约 192 KbpsmaxIdleTime
:(选填)Number 类型,最长空闲频道时间。默认值为 30 秒,该值需大于等于 5,且小于等于 (232-1)。如果频道内无用户的状态持续超过该时间,审核服务会自动退出。
maxIdleTime
,审核服务会自动退出。subscribeAudioUids
:(选填)JSONArray 类型,由 UID 组成的数组,指定订阅哪几个 UID 的音频流。数组长度不得超过 32,不推荐使用空数组。
unSubscribeAudioUids
: (选填)JSONArray 类型,由 UID 组成的数组,指定不订阅哪几个 UID 的音频流。审核服务会订阅频道内除指定 UID 外所有 UID 的音频流。数组长度不得超过 32,不推荐使用空数组。subscribeAudioUids
和 unSubscribeAudioUids
不能同时设置。
subscribeAudioUids
和 unSubscribeAudioUids
不能同时设置。subscribeUidGroup
: (选填)Number 类型,预估的订阅人数峰值。在单流模式下,为必填参数。举例来说,如果 subscribeAudioUids
为 ["100","101","102"]
,则订阅人数为 3 人,该参数需要设置为 1
。
0
: 1 到 2 人1
: 3 到 7 人2
: 8 到 12 人3
: 13 到 17 人扩展服务设置
extensionServiceConfig
是一个用于设置扩展服务的 JSON Object。扩展服务是声网提供的处理音视频流的一系列云端应用,如语音审核服务。extensionServiceConfig
包含以下字段:
errorHandlePolicy
:(选填)String 类型,错误处理策略。目前仅可设为:
"error_abort"
:(默认)当扩展服务发生错误后,订阅等其他服务均停止。apiVersion
:(选填)String 类型,智能语音审核 RESTful API 的版本号,默认为 "v1"
。
extensionServices
:JSONArray 类型,由每个扩展服务的设置组成的数组。本文介绍使用智能语音审核时需要设置的参数。
serviceName
:String 类型,扩展服务的名称。可设为:
shumei_voice_scan
:数美智能语音审核yitu_voice_async_scan
:依图智能语音审核errorHandlePolicy
:(选填)String 类型。错误处理策略。目前仅可设为:
"error_abort"
:(默认)当扩展服务发生错误后,订阅等其他服务均停止。streamTypes
:Number 类型,要审核的媒体流类型。使用智能语音审核时,你需要将其设置为 0
,即仅审核音频。
0
:仅订阅音频1
:仅订阅视频2
:(默认)订阅音频和视频serviceParam
:JSON Object,扩展服务的具体参数设置。当使用智能语音审核时,你需要设置以下字段:
数美
字段 | 类型 | 描述 |
---|---|---|
accessKey |
String | 访问密钥中的 Key ID,用于识别访问者的身份。 |
appId |
String | 项目使用的 app ID,用于标识你的项目应用。 该 appId 为向数美获取的项目 ID,请勿使用声网的 app ID。 |
callback |
String | 接收智能语音审核结果回调的服务器地址。 |
type |
String | 识别类型,包含如下类型: PORN :色情 ABUSE :辱骂AD :广告AUDIOPOLITICAL :一号领导人声纹POLITICAL :涉政MOAN :娇喘ANTHEN :国歌SING :唱歌LANGUAGE :语种MINOR :未成年人BANEDAUDIO :违禁歌曲VOICE :人声属性AUDIOSCENE :声音场景如需组合以上类型,你可以将类型用下划线连接,例如: POLITICAL_PORN_MOAN_AD ,表示用于广告、色情、涉政和娇喘审核。 |
businessType |
String | 识别业务类型,包含如下类型:SING :唱歌LANGUAGE :语种GENDER :性别TIMBRE :音色MINOR :未成年VOICE :人声属性AUDIOSCENE :声音场景如需组合以上类型,你可以将类型用下划线连接,例如: SING_LANGUAGE_GENDER ,表示用于唱歌、语种、性别审核。必须设置 type 和 businessType 其中一个。 |
eventId |
String | 识别场景,包含如下场景: audiobook :有声书education :教育音频game :游戏语音房live :秀场直播ecommerce :电商直播 voiceroom :交友语聊房private :私密语聊default :默认other :其他 |
returnAllText |
Int | (选填) 返回全量或特定的审核结果: |
returnPreText |
Int | (选填) 返回违规片段的文本内容: |
returnPreAudio |
Int | (选填) 返回违规片段的音频链接: |
依图
字段 | 类型 | 描述 |
---|---|---|
callbackAddr |
String | 接收语音审核结果的 HTTP 服务器地址。 |
apiData |
String | 向智能语音审核服务传入的字段值。 |
apiData.accessKey |
String | 访问密钥中的 Key ID,用于识别访问者的身份。 |
apiData.secretKey |
String | 访问密钥中的 Key Secret,用于验证签名的密钥。 |
apiData.bizType |
String | 开通依图智能语音审核服务时向获取到的 AppId。 |
apiData.callbackSeed |
String | 随机字符串,用于回调通知请求中的签名。默认为空。 |
录制文件设置
如果你需要在审核的同时录制音频流,则需要通过
recordingFileConfig
配置录制文件格式;否则,则跳过该参数配置。
recordingFileConfig
是一个 JSON Object,用于设置录制文件。包含以下字段:
avFileType
:(选填)JSONArray 类型,由多个字符串组成的数组,指定录制的视频文件类型。智能语音审核服务会录制生成 avFileType
中包含的所有文件类型。目前支持以下值: "hls"
:默认值,即录制生成 M3U8 和 TS 文件。 "mp4"
:录制生成 MP4 文件。只有在合流模式(mix
)下,才可设置为 "mp4"
。对于合流模式,智能语音审核服务会在当前 MP4 文件时长超过约 2 小时或大小超过约 2 GB 左右时创建一个新的 MP4 文件。"mp4"
的同时必须设置 "hls"
(否则会收到错误码 2),录制结束后,你会同时获得 MP4 和 HLS 文件。云存储设置
如果你需要在审核的同时录制音频流,则需要通过
storageConfig
配置第三方云存储;否则,则跳过该参数配置。
storageConfig
是一个用于设置第三方云存储的 JSON Object,包含以下字段:
vendor
:Number 类型,第三方云存储平台。
region
:Number 类型,第三方云存储指定的地区信息,仅支持以下列表中的地区:
region
与你发起请求的应用服务器必须在同一个区域中。例如:你发起请求的应用服务器在中国大陆地区,则第三方云存储需要设置为中国大陆区域内。vendor
= 0,即第三方云存储为七牛云时:0
:华东1
:华北2
:华南3
:北美4
:东南亚vendor
= 1,即第三方云存储为 Amazon S3 时:0
:US_EAST_11
:US_EAST_22
:US_WEST_13
:US_WEST_24
:EU_WEST_15
:EU_WEST_26
:EU_WEST_37
:EU_CENTRAL_18
:AP_SOUTHEAST_19
:AP_SOUTHEAST_210
:AP_NORTHEAST_111
:AP_NORTHEAST_212
:SA_EAST_113
:CA_CENTRAL_114
:AP_SOUTH_115
:CN_NORTH_116
:CN_NORTHWEST_117
:US_GOV_WEST_120
:AP_NORTHEAST_321
:EU_NORTH_122
:ME_SOUTH_123
:US_GOV_EAST_1vendor
= 2,即第三方云存储为阿里云时:0
:CN_Hangzhou1
:CN_Shanghai2
:CN_Qingdao3
:CN_Beijing4
:CN_Zhangjiakou5
:CN_Huhehaote6
:CN_Shenzhen7
:CN_Hongkong8
:US_West_19
:US_East_110
:AP_Southeast_111
:AP_Southeast_212
:AP_Southeast_313
:AP_Southeast_514
:AP_Northeast_115
:AP_South_116
:EU_Central_117
:EU_West_118
:EU_East_119
:AP_Southeast_620
:CN_Heyuan21
:CN_Guangzhou22
:CN_Chengduvendor
= 3,即第三方云存储为腾讯云时:0
:AP_Beijing_11
:AP_Beijing2
:AP_Shanghai3
:AP_Guangzhou4
:AP_Chengdu5
:AP_Chongqing6
:AP_Shenzhen_FSI7
:AP_Shanghai_FSI8
:AP_Beijing_FSI9
:AP_Hongkong10
:AP_Singapore11
:AP_Mumbai12
:AP_Seoul13
:AP_Bangkok14
:AP_Tokyo15
:NA_Siliconvalley16
:NA_Ashburn17
:NA_Toronto18
:EU_Frankfurt19
:EU_Moscowvendor
= 4,即第三方云存储为金山云时:0
:CN_Hangzhou1
:CN_Shanghai2
:CN_Qingdao3
:CN_Beijing4
:CN_Guangzhou5
:CN_Hongkong6
:JR_Beijing7
:JR_Shanghai8
:NA_Russia_19
:NA_Singapore_1vendor
= 5,即第三方云存储为 Microsoft Azure 时:region
参数,即使设置也不生效。
vendor
= 6,即第三方云存储为谷歌云时:region
参数,即使设置也不生效。
vendor
= 7,即第三方云存储为华为云时:0
:CN_North_11
:CN_North_42
:CN_East_23
:CN_East_34
:CN_South_15
:CN_Southwest_26
:AP_Southeast_17
:AP_Southeast_28
:AP_Southeast_39
:AF_South_110
:SA_Argentina_111
:SA_Peru_112
:NA_Mexico_113
:SA_Brazil_114
:LA_South_215
:SA_Chile_1vendor
= 8,即第三方云存储为百度智能云时:0
:Beijing1
:Baoding2
:Suzhou3
:Guangzhou4
:Hongkong5
:Singapore6
:Wuhan7
:Shanghaibucket
:String 类型,第三方云存储的 bucket,bucket 名称需要符合对应第三方云存储服务的命名规则。
accessKey
:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。如需延时转码,则访问密钥必须同时具备读写权限。
secretKey
:String 类型,第三方云存储的 secret key。
fileNamePrefix
:(选填)JSONArray 类型,由多个字符串组成的数组,指定录制文件在第三方云存储中的存储位置。举个例子,fileNamePrefix
= ["directory1","directory2"]
,将在录制文件名前加上前缀 "directory1/directory2/
",即 directory1/directory2/xxx.m3u8
。前缀长度(包括斜杠)不得超过 128 个字符。字符串中不得出现斜杠、下划线、括号等符号字符。以下为支持的字符集范围:
extensionParams
:(选填)JSON Object 类型,第三方云存储服务会按照该参数设置对已上传的录制文件进行加密和打标签。包含以下字段:
sse
:加密模式。设置该字段后,第三方云存储服务会按照该加密模式将已上传的录制文件进行加密。该字段仅适用于 Amazon S3,详见 Amazon S3 官方文档。可设为:
kms
:KMS 加密。aes256
:AES256 加密。tag
:标签内容。设置该字段后,第三方云存储服务会按照该标签内容将已上传的录制文件进行打标签操作。该字段仅适用于阿里云和 Amazon S3,详见阿里云官方文档和 Amazon S3 官方文档。
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start
Content-type
为 application/json;charset=utf-8
Authorization
为 Basic authorization,生成方法请参考 RESTful API 认证。语音审核(单流模式)
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "yitu_voice_async_scan", // 或 shumei_voice_scan
"serviceParam": {
"apiData": {
"accessKey": "xxxx",
"bizType": "xxxx", // 仅当使用依图智能语音审核时需要设置
"callbackSeed": "xxxx",
"secretKey": "xxxx"
},
"callbackAddr": "http://xxxx"
},
"streamTypes": 0
}
]
},
"recordingConfig": {
"channelType": 1,
"maxIdleTime": 30,
"streamTypes": 0,
"subscribeUidGroup": 0
}
}
}
语音审核并录制(单流模式)
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "yitu_voice_async_scan", // 或 shumei_voice_scan
"serviceParam": {
"apiData": {
"accessKey": "xxxx",
"bizType": "xxxx", // 仅当使用依图智能语音审核时需要设置
"callbackSeed": "xxxx",
"secretKey": "xxxx"
},
"callbackAddr": "http://xxxx"
},
"streamTypes": 0
}
]
},
"recordingConfig": {
"channelType": 1,
"maxIdleTime": 30,
"streamTypes": 0,
"subscribeUidGroup": 0
},
"recordingFileConfig": {
"avFileType": ["hls"]
},
"storageConfig": {
"accessKey": "xxxx",
"bucket": "xxxx",
"fileNamePrefix": ["directory1", "directory2"],
"region": 0,
"secretKey": "xxxx",
"vendor": 0
}
}
}
语音审核(合流模式)
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "yitu_voice_async_scan", // 或 shumei_voice_scan
"serviceParam": {
"apiData": {
"accessKey": "xxxx",
"bizType": "xxxx", // 仅当使用依图智能语音审核时需要设置
"callbackSeed": "xxxx",
"secretKey": "xxxx"
},
"callbackAddr": "http://xxxx"
},
"streamTypes": 0
}
]
},
"recordingConfig": {
"audioProfile": 2,
"channelType": 1,
"maxIdleTime": 30,
"streamTypes": 0
}
}
}
语音审核并录制 HLS 文件(合流模式)
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "yitu_voice_async_scan", // 或 shumei_voice_scan
"serviceParam": {
"apiData": {
"accessKey": "xxxx",
"bizType": "xxxx", // 仅当使用依图智能语音审核时需要设置
"callbackSeed": "xxxx",
"secretKey": "xxxx"
},
"callbackAddr": "http://xxxx"
},
"streamTypes": 0
}
]
},
"recordingConfig": {
"audioProfile": 2,
"channelType": 1,
"maxIdleTime": 30,
"streamTypes": 0
},
"recordingFileConfig": {
"avFileType": ["hls"]
},
"storageConfig": {
"accessKey": "xxxx",
"bucket": "xxxx",
"fileNamePrefix": ["directory1", "directory2"],
"region": 0,
"secretKey": "xxxx",
"vendor": 0
}
}
}
语音审核并录制 HLS 和 MP4 文件(合流模式)
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"extensionServiceConfig": {
"apiVersion": "v1",
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"errorHandlePolicy": "error_abort",
"serviceName": "yitu_voice_async_scan", // 或 shumei_voice_scan
"serviceParam": {
"apiData": {
"accessKey": "xxxx",
"bizType": "xxxx", // 仅当使用依图智能语音审核时需要设置
"callbackSeed": "xxxx",
"secretKey": "xxxx"
},
"callbackAddr": "http://xxxx"
},
"streamTypes": 0
}
]
},
"recordingConfig": {
"audioProfile": 2,
"channelType": 1,
"maxIdleTime": 30,
"streamTypes": 0
},
"recordingFileConfig": {
"avFileType": ["hls", "mp4"]
},
"storageConfig": {
"accessKey": "xxxx",
"bucket": "xxxx",
"fileNamePrefix": ["directory1", "directory2"],
"region": 0,
"secretKey": "xxxx",
"vendor": 0
}
}
}
"Code": 200,
"Body":
{
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
:Number 类型,响应状态码。resourceId
:String 类型,智能语音审核使用的 resource ID。sid
:String 类型,审核 ID。成功开始智能语音审核后,你会得到一个 sid (审核 ID)。该 ID 是一次审核的唯一标识。开始审核后,你可以调用 query
查询审核状态。
query
请求仅在会话内有效。如果审核启动错误,或审核已结束,调用 query
将返回 404。
每个 App ID 每秒钟的请求数限制为 10 次。如需提高此限制,请联系技术支持。
该 API 需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appid | String | 你的项目使用的 App ID。必须使用和待审核的频道相同的 App ID。 |
resourceid | String | 通过 acquire 请求获取的 resource ID。 |
sid | String | 通过 start 请求获取的审核 ID。 |
mode | String | 审核模式,支持以下模式:individual ):分开审核频道内每个 UID 的音频流。mix ):将频道内所有(或指定)UID 的音频流混合为一路流后进行审核。 |
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query
Content-type
为 application/json;charset=utf-8
Authorization
为 Basic authorization,生成方法请参考 RESTful API 认证。单流模式
"Code": 200,
"Body":
{
"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": "aliyun_voice_async_scan", // 或 yitu_voice_async_scan
"streamState": [
{
"status": "inProgress",
"streamType": "audio",
"uid": "0"
}
]
}
],
"subServiceStatus": {
"recordingService": "serviceInProgress",
"uploadingService": "serviceInProgress",
"mediaDistributeService": "serviceInProgress"
},
"status": 5,
"fileList": "xxxx.m3u8",
"fileListMode": "string",
"sliceStartTime": 0
}
}
合流模式
"Code": 200,
"Body":
{
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"serverResponse": {
"subServiceStatus": {
"recordingService": "serviceInProgress",
"mediaDistributeService": "serviceInProgress"
},
"extensionServiceState": [
{
"serviceName": "aliyun_voice_async_scan", // 或 yitu_voice_async_scan
"streamState": [
{
"status": "inProgress",
"streamType": "audio",
"uid": "0"
}
]
}
]
}
}
code
:Number 类型,响应状态码。resourceId
:String 类型,智能语音审核的 resource ID。sid
:String 类型,通过 start
请求获取的审核 ID。serverResponse
:JSON Object,服务器返回的具体信息。subServiceStatus
:JSON Object,子模块的服务状态。
extensionServiceState
:JSONArray 类型,由各个扩展服务的当前状态组成的数组。serviceName
:String 类型,扩展服务的名称:shumei_voice_scan
:数美智能语音审核yitu_voice_async_scan
:依图智能语音审核streamState
:JSONArray 类型,该扩展服务的状态。当选择数美或依图智能语音审核时,返回以下参数:uid
:Number 类型,用户 UID,表示审核的是哪个用户的媒体流。合流模式下,uid
总为 0
。streamType
:String 类型,审核的内容类型。"audio"
指纯音频。status
:审核的状态。"inProgress"
:审核正在进行中。"failed"
:审核发生错误。审核完成后,调用该方法离开频道,停止审核。审核停止后如需再次审核,必须再调用 acquire
方法请求一个新的 resource ID。
- 每个 App ID 每秒钟的请求数限制为 10 次。如需提高此限制,请联系技术支持。
- 当频道空闲(无用户)超过预设时间(默认为 30 秒) 后,智能语音审核也会自动退出频道停止审核。
该 API 需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appid |
String | 你的项目使用的 [App ID](https://docs.agora.io/cn/Agora%20Platform/terms?platform=All Platforms#a-name-appid-a-app-id)。必须使用和待审核的频道相同的 App ID。 |
resourceid |
String | 通过 acquire 请求获取的 resource ID。 |
sid |
String | 通过 start 请求获取的审核 ID。 |
mode |
String | 审核模式,支持以下模式:单流模式(individual) :分开审核频道内每个 UID 的音频流。合流模式(mix): 将频道内所有(或指定)UID 的音频流混合为一路流后进行审核。 |
该 API 需要在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
cname |
String | 待审核的频道名。 |
uid |
String | 字符串内容为智能语音审核使用的 UID,需要和你在 acquire 请求中输入的 uid 相同。 |
clientRequest |
JSON | 特定的客户请求参数,对于该方法无需填入任何内容,为一个空的 JSON。 |
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop
Content-type
为 application/json;charset=utf-8
Authorization
为 Basic authorization,生成方法请参考 RESTful API 认证。{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {}
}
"Code": 200,
"Body":
{
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
:Number 类型,响应状态码。resourceId
:String 类型,智能语音审核使用的 resource ID。sid
:String 类型,审核 ID。成功开始智能语音审核后,你会得到一个 sid (审核 ID)。该 ID 是一次审核的唯一标识。智能语音审核的审核结果,会以 HTTP 请求的形式直接发送到你在 extensionServiceConfig
中的 callbackAddr
设置的地址。回调内容详见对应的第三方智能语音审核官方文档中关于返回参数的说明。除此之外,该回调还会包含 dataId
字段,包含以下信息:
channelName
:String 类型,此次审核的频道名。
uid
:String 类型,语音审核的用户所属 UID。uid
为 0 表示语音审核为合流模式。
streamType
:String 类型,智能语音审核所审核的内容类型。"audio"
表示纯音频。
状态 | 描述 |
---|---|
"serviceIdle" | 子模块服务未开始。 |
"serviceStarted" | 子模块服务已开始。 |
"serviceReady" | 子模块服务已就绪。 |
"serviceInProgress" | 子模块服务正在进行中。 |
"serviceCompleted" | 审核内容已全部上传至智能语音审核。 |
"servicePartialCompleted" | 审核内容部分上传至智能语音审核。 |
"serviceValidationFailed" | 智能语音审核验证失败。例如 extensionServiceConfig 中 apiData 填写错误。 |
"serviceAbnormal" | 子模块状态异常。 |
状态码 | 描述 |
---|---|
200 | 请求成功。 |
201 | 成功请求并创建了新的资源。 |
206 | 整个审核过程中没有用户发流。 |
400 | 请求的语法错误(如参数错误)。如果你填入的 App ID 没有开通第三方智能语音审核服务,也会返回 400。 |
401 | 未经授权的(客户 ID/客户密钥匹配错误)。 |
404 | 服务器无法根据请求找到资源(网页)。 |
500 | 服务器内部错误,无法完成请求。 |
504 | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 |
下面仅列出使用智能语音审核 RESTful API 过程中常见的错误码或错误信息,如果遇到其他错误,请联系声网技术支持。
2
:参数不合法,请确保参数类型正确、大小写正确、必填的参数均已填写。
7
:审核已经在进行中 ,请勿用同一个 resource ID 重复 start
请求。
8
:HTTP 请求头部字段错误,有以下几种情况:
Content-type
错误,请确保 Content-type
为 application/json;charset=utf-8
。cloud_recording
字段。49
:使用同一个 resource ID 和审核 ID(sid
)重复 stop
请求。
53
:审核已经在进行中。当采用相同参数再次调用 acquire
获得新的 resource ID,并用于 start
请求时,会发生该错误。如需发起多路审核,需要在 acquire
方法中填入不同的 UID。
62
:调用 acquire
请求时,如果出现该错误,表示你填入的 App ID 没有开通第三方智能语音审核服务。
65
:多为网络抖动引起。使用相同 resource ID 重试即可。
432
:请求参数错误。请求参数不合法。
433
:resource ID 过期。获得 resource ID 后必须在 5 分钟内开始审核。请重新调用 acquire
获取新的 resource ID。
435
:频道内没有用户加入,无审核对象。
501
:审核正在退出。该错误可能在调用了 stop
方法后再调用 query
时发生。
1001
:resource ID 解密失败。请重新调用 acquire
获取新的 resource ID。
1003
:App ID 或者审核 ID(sid)与 resource ID 不匹配。请确保在一个审核周期内 resource ID、App ID 和审核 ID 一一对应。
1013
:频道名不合法。频道名必须为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
"invalid appid"
:无效的 App ID。请确保 App ID 填写正确。如果你已经确认 App ID 填写正确,但仍出现该错误,请联系技术支持。
"no Route matched with those values
": 该错误可能由 HTTP 方法填写错误导致,例如将 GET 方法填写为 POST;也可能由请求 URL 填写错误导致。
"Invalid authentication credentials"
:该错误可能由以下原因导致。 如果你已经排除以下原因,但仍出现该错误,请提交工单。
Authorization
字段的值 Basic <Authorization>
缺少 Basic
。Content-type
字段的值 application/json;charset=utf-8
大小写不正确或包含空格。