#
智能音频流识别产品API文档版权所有 翻版必究
目录
版本
版本号 | 更新时间 | 作者 | 更新说明 |
---|---|---|---|
V1.9.5 | 2021/06/05 | 张阳 | 1. 新增版本说明 2. 新增seiInfo字段展示sei信息 |
V1.9.6 | 2021/07/28 | 张阳 | 1. 新增语种识别 |
V1.9.7 | 2021/07/28 | 张阳 | 1. 新增语种识别 |
V1.9.8 | 2021/08/06 | 毛帅 | 1. 新增用户角色字段,role 2. 调整audioText含义为前一个片段内容 3. 优化preAudioUrl逻辑为前一个音频片段 |
V2.0.0 | 2021/10/29 | 刘拴朋 | 1.添加trtcUserId字段 |
V2.0.1 | 2021/11/08 | 刘拴朋 | 1.添加海外url地址,删除北京url |
V2.0.2 | 2021/11/23 | 惠聪 | 1. 添加业务标签入参businessType,返回businessLabels 2. 新增风险来源字段riskSource |
V2.0.3 | 2021/12/07 | 惠聪 | 1.新增加间隔审核功能,关键字段audioDetectStep 2.returnPreText功能说明改动 3.returnPreAudio功能说明改动 4.支持集群更新 |
V2.0.4 | 2021/12/27 | 刘拴朋 | 1. trtcUserId替换为strUserId字段 |
V2.0.5 | 2022/03/29 | 朱晓峰 | 1. 增加声网renew token功能 |
V2.0.7 | 2022/04/18 | 代俊凯 | 1. 增加callbackParam说明 |
V2.0.8 | 2022/05/09 | 代俊凯 | 1. 增加违禁歌曲、人声属性、声音场景识别 |
#
1. 接入前准备#
1.1 数美服务账号申请客户经理已提前与贵公司建立联系或当面拜访,可直接将开通账号及服务相关信息提供至客户经理。
开通账号所需信息包括:
公司全称:xxxxxx
公司简称:xxxxxx
接口人邮箱:xxx@xxx.xxx
接口人手机:1xxxxxxxxxx
#
1.2 渠道配置表数美根据客户不同业务场景,配置不同的渠道(channel),制定针对性的拦截策略,同时也方便客户针对不同业务场景的数据进行筛选、分析。业务场景和渠道取值对应表如下(支持客户自定义):
业务场景 | channel取值 | 备注 |
---|---|---|
语音房 | VOICE_ROOM | 多人连麦语音房 |
直播间 | LIVE_ROOM | 视频直播间 |
语音聊天 | VOICE_CHAT | 两人语音聊天通话 |
#
1.2 数美服务账号信息接收数美客户经理会在1个工作日内为您开通相应数美账号及服务,随后接口人邮箱会收到如下信息:
名称 | 具体值 | 说明 |
---|---|---|
accessKey | xxxxxx | 数美API服务的认证码,调用数美API时需要传入 |
organization | xxxxxx | 数美分配的企业唯一标识码,调用SDK时需要传入 |
数美管理后台账号 | xxxxxx | 用于登陆数美管理后台 |
数美管理后台密码 | xxxxxx | 用于登陆数美管理后台 |
数美管理后台地址 | https://www.fengkongcloud.com | 用于登陆数美管理后台 |
#
2. 智能音频流过滤服务接口说明数美智能音频流过滤服务方案提供音频流内容检测和音频流关闭通知接口。
#
2.1 音频流检测请求#
接口描述该接口用于提交音频流相关信息,接口会实时检测音频流中是否出现违规内容,并通过回调把违规信息发送给客户指定的url。
#
请求URL上海集群:
http://api-audiostream-sh.fengkongcloud.com/v2/saas/anti_fraud/audiostream
硅谷集群:
http://api-audiostream-gg.fengkongcloud.com/v2/saas/anti_fraud/audiostream
新加坡:
http://api-audiostream-xjp.fengkongcloud.com/v2/saas/anti_fraud/audiostream
#
字符编码格式请求及返回结果都使用UTF-8字符集进行编码
#
请求方法POST
#
建议超时时长3s
#
通用请求参数放在HTTP Body中,采用Json格式,具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
accessKey | string | Y | 服务密钥,开通账号服务时由数美提供 |
type | string | N | 识别类型,可选值: PORN:色情识别 AD:广告识别 AUDIOPOLITICAL:一号领导人声纹识别 POLITICAL:涉政识别 MOAN:娇喘识别 ANTHEN:国歌识别 SING:唱歌识别 LANGUAGE:语种识别 MINOR:未成年人识别 BANEDAUDIO:违禁歌曲 VOICE:人声属性 AUDIOSCENE:声音场景 如需做组合识别,通过下划线连接即可,例 如 POLITICAL_PORN_MOAN_AD 用于广告、色情和涉政,娇喘识别。 type和 businessType 必须填其一 |
businessType | string | N | 识别类型,可选值: SING:唱歌 LANGUAGE:语种 GENDER:性别 TIMBRE:音色 MINOR:未成年 VOICE:人声属性 AUDIOSCENE:声音场景 type和 businessType 必须填其一 |
btId | string | Y | 音频唯一标识,用于查询指定音频,限长128位字符长度 |
appId | string | N | 应用标识 用于区分相同公司的不同应用,该参数传递值可与数美服务协商用于区分应用 默认应用值:default |
callback | string | Y | 异步检测结果回调通知您的URL,支持HTTP和HTTPS |
data | json_object | Y | 请求数据内容,最长1MB |
其中,data的内容如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
streamType | string | Y | 流类型:可选择: 声网录制:AGORA 即构录制:ZEGO 腾讯录制:TRTC |
url | string | Y | 要检测的音频流url地址(当streamType为NORMAL时必传) |
agoraParam | json_object | Y | 声网录制参数(当streamType为AGORA时必传),详见扩展参数 |
zegoParam | json_object | Y | 即构录制参数(当streamType为ZEGO时必传),详见扩展参数 |
trtcParam | json_object | Y | 腾讯录制参数(当streamType为TRTC时必传),详见扩展参数 |
tokenId | string | Y | 客户端用户账号唯一标识, |
channel | string | Y | 见渠道配置表 |
callbackParam | json_object | N | 透传参数 |
#
扩展请求参数放在data下,其中具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
room | string | N | 房间号,强烈建议传入 |
role | string | N | 用户角色 对不同角色可配置不同策略。 直播领域可取值: 房管:ADMIN 主播:HOST 系统角色:SYSTEM 游戏领域可取值: 管理员:ADMIN 普通用户:USER 默认值:普通用户 |
returnAllText | bool | N | 取值为true时返回全量的音频流片段识别结果和文本内容; 取值为false时只返回有风险(riskType为REJECT)的音频流片段识别结果和文本内容,默认是false |
returnPreText | bool | N | 值为true时,返回的content字段包含违规音频前一个片段10秒文本内容; 值为false时,返回的content字段只包含违规音频片段文本内容,默认值为false(对于TRTC流该功能无效,当客户使用间隔审核功能时,即使returnPreAudio是true情况下,也不返回该字段) |
returnPreAudio | bool | N | 值为true,返回违规音频前一个片段10秒链接;值为false时,只返回违规片段音频链接。默认值为false(对于TRTC流该功能无效), 当客户使用间隔审核功能时,即使returnPreText为true情况下,也只返回当前片段文本,不返回前一个片段的文本。 |
returnFinishInfo | bool | N | 音频流结束回调通知 可选值(默认为false): true:审核结束时发起结束通知,回调参数增加statCode状态码 |
initDomain | int | N | 当即构客户端init初始化支持隔离域名和随机userId该字段必传,可选值:1 :仅支持客户端初始化有隔离域名2 :支持客户端初始化有隔离域名和随机userId功能名 |
audioDetectStep | int | N | 音频每个步长只会检测一次,取值范围1-5的整数,默认每个片段都审核(备注) |
其中data.agoraParam内容如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
appId | string | Y | 声网提供的appId,注意与数美的appId区分开 |
channel | string | Y | 声网提供的频道名,注意与数美channel区分开。 |
token | string | N | 安全要求较高的用户可以使用 Token进行认证,生成方式详见声网文档: https://docs.agora.io/cn/Interactive%20Broadcast/token_server?platform=All%20Platforms 数美建议token最小有效期为15分钟以上 |
uid | int | N | 用户 ID,32 位无符号整数。当token存在时,必须提供生成token时所使用的用户ID。注意,此处需要区别实际房间中的用户uid,提供给服务端录制所用的uid不允许在房间中存在。 |
isMixingEnabled | bool | N | 单流/合流录制,默认合流录制。 true:合流 false:分流 合流是指一个直播房间一路流,分流是指一个麦位一路流 |
channelProfile | int | N | 声网录制的频道模式,取值: 0: 通信(默认),即常见的 1 对 1 单聊或群聊,频道内任何用户可以自由说话; 1: 直播,有两种用户角色: 主播和观众。 默认以通信模式录制,即默认值为0。 |
renewTokenURL | string | N | 用于更新声网Token的接口,详见更新声网Token接口规范 如果不提供该参数,则不会更新Token,当Token失效时就该声网流无法继续审核 |
其中data.zegoParam内容如下
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
tokenId | string | Y | zego提供的身份验证信息,用于token登陆 |
streamId | string | Y | 用户设置的音频流编号,唯一对应一路音频流,streamId与roomId至少存在其中之一,如果streamId与roomId同时存在时,streamId有效;当streamId生效时,服务端以用户为单位拉流。 |
roomId | string | Y | 用户设置的房间编号,唯一对应一个房间,streamId与roomId至少存在其中之一,如果streamId与roomId同时存在时,streamId有效;当roomId生效时,服务端以房间为单位拉流。 |
testEnv | bool | Y | 是否使用zego测试环境,指定true时为测试环境,指定false时为正式环境。默认为false |
其中 data.trtcParam内容如下
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
sdkAppId | int | Y | 腾讯提供的sdkAppId |
demoSences | int | Y | 录制类型可选值: 分流录制:2 |
userId | string | Y | 分配给录制段的userId,限制长度为32bit,只允许包含(a-zA-Z),数字(0-9)以及下划线和连词符 |
userSig | string | Y | 录制userId对应的验证签名,相当于登录密码 |
roomId | int | Y | 房间号码,取值范围:【1-4294967294】 roomId与strRoomId必传一个,若两者都有值优先选用roomId |
strRoomId | string | Y | 房间号码 若您选用strRoomId时,需注意strRoomId和roomId两者都有值优先选用roomId |
#
返回参数放在HTTP Body中,采用Json格式,具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
code | int | Y | 返回码 |
message | string | Y | 返回码详情描述 |
requestId | string | Y | 请求唯一标识 |
detail | json_object | N | 描述详细信息 |
detail结构如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
errorCode | int | Y | 状态码 |
errorCode对应说明如下:
code | message |
---|---|
1001 | 重复推流 |
#
回调策略当用户收到推送结果,并返回HTTP状态码为200时,表示推送成功;否则
系统将进行最多12次推送。
#
请求方法POST
#
字符编码格式请求及返回结果都使用UTF-8字符集进行编码
#
回调参数放在HTTP Body中,采用Json格式,具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
code | int | Y | 返回码 |
message | string | Y | 返回码详情描述 |
requestId | string | Y | 请求唯一标识 |
score | int | N | 风险分数(code 为 1100 且riskLevel=REJECT时存在) 取值范围[0,1000],分数越高风险越大 |
riskLevel | string | Y | 风险级别(code 为 1100 时存在) 可能返回值:PASS,REVIEW,REJECT PASS:正常内容,建议直接放行 REVIEW:可疑内容,建议人工审核 REJECT:违规内容,建议直接拦截 |
statCode | int | N | 审核状态: 0 :审核中: 1 :审核结束 |
detail | json_object | Y | 风险详情 |
其中,detail 的内容如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
beginProcessTime | int | Y | 开始处理的时间(13位时间戳) |
finishProcessTime | int | Y | 结束处理的时间(13位时间戳) |
audioUrl | string | Y | 音频片段地址,returnAllText不传或为false时只返回违规音频片段地址, returnAllText为true时返回所有音频片段地址 |
preAudioUrl | string | N | 违规内容前一个10秒音频片段地址(该参数只有在请求参数中returnPreAudio是true情况下存在) |
audio_endtime | string | Y | 违规内容结束时间(绝对时间) |
audio_starttime | string | Y | 违规内容开始时间(绝对时间) |
audioText | string | Y | 音频片段文本 |
content | string | N | returnPreText为true时返回违规内容前一个片段10秒文本和违规内容片段文本 |
description | string | Y | 策略规则风险原因描述 注:该参数为旧版 API 返回参数,兼容保留, 后续版本将去除,请勿依赖此参数,仅供参考 |
descriptionV2 | string | Y | 策略规则风险原因描述 注:该参数为 API 返回参数 请勿依赖此参数,仅供参考 |
matchedItem | string | N | 命中的具体敏感词(该参数仅在命中敏感词时存在) |
matchedList | string | N | 命中敏感词所在的名单名称(该参数仅在命中 敏感词时存在) |
hits | json_array | Y | 展示风险详情,请勿依赖此参数,仅供参考 |
model | string | Y | 规则标识,用来标识文本命中的策略规则。 注:该参数为旧版 API 返回参数,兼容保留, 后续版本将去除,请勿依赖此参数,仅供参考 |
isSing | int | N | type取值包含SING时存在,取值0表示检测不存在唱歌片段,取值1表示检测存在唱歌片段 |
requestParams | json_object | Y | 返回请求参数data中的所有字段 |
riskType | int | Y | 标识风险类型,可能取值: 100:涉政 110:暴恐 120:国歌 200:色情 210:辱骂 250:娇喘 260:一号领导声纹 270:人声属性 280:违禁歌曲 300:广告 400:灌水 500:无意义 520:未成年人 600:违禁 700:其他 720:黑账号 730:黑IP 800:高危账号 900:自定义 |
riskTypeDesc | string | N | 风险原因描述 |
room | string | Y | 房间号 |
userId | int | N | 用户账号标识(仅分流情况下存在)。返回的userId是实际房间中的用户id,与请求参数中的uid无关。 |
strUserId | string | N | 用户账号标识(仅TRTC分流情况下存在)。返回的userId是实际房间中的用户id,与请求参数中的uid无关。 |
vadCode | int | N | 静音状态: 0 :静音片段 1 :非静音片段 |
seiInfo | array | N | (需要联系数美开通) 展示流片段插入的SEI信息 |
language | json_array | N | 语种识别与概率值列表,在type下传入返回。 |
minorLabel | int | N | 当type传入MINOR且命中未成年人标签时,才会返回; 1:未成年人 |
businessLabels | json_array | Y | 音频业务标签返回 |
riskSource | int | Y | 风险来源 1000:无风险 1001:文字 1003:音频 |
detail.language数组中每一项具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
label | int | Y | 语种识别类别标识,可能取值: 0:普通话 1:英语 2:粤语 |
confidence | int | Y | 对应语种标签可能性大小,取值0-100,数值越高表示概率越大。 |
其中,businessLabels详细内容如下:
参数名 | 类型 | 参数说明 | 是否必返 | 备注 |
---|---|---|---|---|
businessLabel1 | string | 一级业务标签 | 否 | |
businessLabel2 | string | 二级业务标签 | 否 | |
businessLabel3 | string | 三级业务标签 | 否 | |
businessDescription | string | 业务标签描述 | 否 | 中文标签描述 |
code和message的列表如下:
Code | message |
---|---|
1100 | 成功 |
1902 | 参数不合法 |
1903 | 服务失败 |
9100 | 余额不足 |
9101 | 无权限操作 |
#
示例#
请求示例#
返回示例#
回调接口返回的内容示例#
2.2 音频流关闭通知接口#
接口描述该接口用于客户端通知服务端某个音频流已关闭。
#
请求URL上海集群:
http://api-audiostream-sh.fengkongcloud.com/v2/saas/anti_fraud/finish_audiostream
硅谷集群:
http://api-audiostream-gg.fengkongcloud.com/v2/saas/anti_fraud/finish_audiostream
新加坡:
http://api-audiostream-xjp.fengkongcloud.com/v2/saas/anti_fraud/finish_audiostream
#
字符编码格式请求及返回结果都使用UTF-8字符集进行编码
#
请求方法POST
#
建议超时时长1s
#
请求参数放在HTTP Body中,采用Json格式,具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
accessKey | string | Y | 用于权限认证,开通账号服务时由数美提供 |
requestId | string | Y | 关闭的音频流的requestId |
#
返回参数放在HTTP Body中,采用Json格式,具体参数如下:
参数名称 | 类型 | 是否必选 | 说明 |
---|---|---|---|
code | int | Y | 返回码 |
message | string | Y | 返回码详情描述 |
requestId | string | Y | 请求唯一标识 |
code和message的列表如下:
Code | message |
---|---|
1100 | 成功 |
1902 | 参数不合法 |
1903 | 服务失败 |
9100 | 余额不足 |
9101 | 无权限操作或accessKey错误 |
#
示例#
请求示例#
返回示例#
3.更新声网Token接口规范声网的Token存在有效期,过期后需要更新Token,详见:
https://docs.agora.io/cn/Agora%20Platform/channel_key
当声网的Token失效时,数美会根据客户提供的renewTokenURL接口获取更新后的Token。
为了统一,该接口需要满足以下规范:
#
请求方式POST
#
请求参数至少会携带以下字段:
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
requestId | string | Y | 开启审核时的requestId |
streamType | string | Y | 返回码详情描述 |
data | json_object | Y | 在请求更新Token接口时,会携带客户开启审核时的部分参数 |
data字段结构:
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
agoraParam | json_object | Y | 与客户当时开启审核时传的参数一致,详见开启审核接口中的data.agoraParam |
#
返回结果至少需要返回以下字段:
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
code | int | Y | 0为成功,非0代表失败 |
msg | string | Y | code为0时:成功 code非0时:具体失败原因 |
token | string | Y | 更新后的声网Token。如果是失败的情况,则不返回token或将token置为空字符串 数美建议token最小有效期为15分钟以上 |
#
3. FAQ#
3.1 调用接口返回参数错误(1902)答:调用数美接口时,code返回1902参数不合法,一般为客户输入的参数格式存在问题,客户可自行分析一下请求格式是否按照接口文档输入,或将请求的数据及返回数据反馈给数美分析解决。
#
3.2 调用接口返回无权限操作(9101)答:调用数美接口时,code返回9101无权限操作,一般为调用了未开通的服务,沟通确认客户调用的服务接口,开通相应的服务。
#
3.3 调用接口超时问题答:有如下两个常见问题:
1)DNS问题:
客户通过公网调用数美接口进行测试,客户DNS解析域名较慢,导致第一次请求超时,建议客户更换DNS,不建议客户在host中将域名和ip做绑定,数美更换接口IP导致无法请求接口。
2)网络问题:
客户通过公网调用数美接口,公网网络延迟较长,导致少量请求存在超时。可以建议客户ping数美不同的集群网络,建议客户接入网络延迟较低的数美集群。
#
3.4 数美接口支持哪些网络协议?数美音频流测试接口支持http、https、RTMP、HLS、HDL(HTTP-FLV)、RTP等所有主流网络协议。