智能音频流识别产品API文档#


版权所有 翻版必究


目录

版本

版本号更新时间作者更新说明
V1.9.52021/06/05张阳

1. 新增版本说明

2. 新增seiInfo字段展示sei信息

V1.9.62021/07/28张阳1. 新增语种识别
V1.9.72021/07/28张阳1. 新增语种识别
V1.9.82021/08/06毛帅

1. 新增用户角色字段,role

2. 调整audioText含义为前一个片段内容

3. 优化preAudioUrl逻辑为前一个音频片段

V2.0.02021/10/29刘拴朋1.添加trtcUserId字段
V2.0.12021/11/08刘拴朋1.添加海外url地址,删除北京url
V2.0.22021/11/23惠聪

1. 添加业务标签入参businessType,返回businessLabels

2. 新增风险来源字段riskSource

V2.0.32021/12/07惠聪

1.新增加间隔审核功能,关键字段audioDetectStep

2.returnPreText功能说明改动

3.returnPreAudio功能说明改动

4.支持集群更新

V2.0.42021/12/27刘拴朋1. trtcUserId替换为strUserId字段
V2.0.52022/03/29朱晓峰1. 增加声网renew token功能
V2.0.72022/04/18代俊凯1. 增加callbackParam说明
V2.0.82022/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个工作日内为您开通相应数美账号及服务,随后接口人邮箱会收到如下信息:

名称具体值说明
accessKeyxxxxxx数美API服务的认证码,调用数美API时需要传入
organizationxxxxxx数美分配的企业唯一标识码,调用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格式,具体参数如下:

参数名称类型是否必选说明
accessKeystringY服务密钥,开通账号服务时由数美提供
typestringN

识别类型,可选值:

PORN:色情识别
ABUSE: 辱骂识别

AD:广告识别

AUDIOPOLITICAL:一号领导人声纹识别

POLITICAL:涉政识别

MOAN:娇喘识别

ANTHEN:国歌识别

SING:唱歌识别

LANGUAGE:语种识别

MINOR:未成年人识别

BANEDAUDIO:违禁歌曲

VOICE:人声属性

AUDIOSCENE:声音场景

如需做组合识别,通过下划线连接即可,例

如 POLITICAL_PORN_MOAN_AD 用于广告、色情和涉政,娇喘识别。

type和 businessType 必须填其一

businessTypestringN

识别类型,可选值:

SING:唱歌

LANGUAGE:语种

GENDER:性别

TIMBRE:音色

MINOR:未成年

VOICE:人声属性

AUDIOSCENE:声音场景

type和 businessType 必须填其一

btIdstringY音频唯一标识,用于查询指定音频,限长128位字符长度
appIdstringN

应用标识

用于区分相同公司的不同应用,该参数传递值可与数美服务协商用于区分应用

默认应用值:default

callbackstringY异步检测结果回调通知您的URL,支持HTTP和HTTPS
datajson_objectY请求数据内容,最长1MB

其中,data的内容如下:

参数名称类型是否必选说明
streamTypestringY

流类型:可选择:
流地址:NORMAL

声网录制:AGORA

即构录制:ZEGO

腾讯录制:TRTC

urlstringY要检测的音频流url地址(当streamType为NORMAL时必传)
agoraParamjson_objectY声网录制参数(当streamType为AGORA时必传),详见扩展参数
zegoParamjson_objectY即构录制参数(当streamType为ZEGO时必传),详见扩展参数
trtcParamjson_objectY腾讯录制参数(当streamType为TRTC时必传),详见扩展参数
tokenIdstringY客户端用户账号唯一标识,
channelstringY见渠道配置表
callbackParamjson_objectN透传参数

扩展请求参数#

放在data下,其中具体参数如下:

参数名称类型是否必选说明
roomstringN房间号,强烈建议传入
rolestringN

用户角色

对不同角色可配置不同策略。

直播领域可取值:

房管:ADMIN

主播:HOST

系统角色:SYSTEM

游戏领域可取值:

管理员:ADMIN

普通用户:USER

默认值:普通用户

returnAllTextboolN

取值为true时返回全量的音频流片段识别结果和文本内容;

取值为false时只返回有风险(riskType为REJECT)的音频流片段识别结果和文本内容,默认是false

returnPreTextboolN

值为true时,返回的content字段包含违规音频前一个片段10秒文本内容;

值为false时,返回的content字段只包含违规音频片段文本内容,默认值为false(对于TRTC流该功能无效,当客户使用间隔审核功能时,即使returnPreAudio是true情况下,也不返回该字段)

returnPreAudioboolN

值为true,返回违规音频前一个片段10秒链接;值为false时,只返回违规片段音频链接。默认值为false(对于TRTC流该功能无效),

当客户使用间隔审核功能时,即使returnPreText为true情况下,也只返回当前片段文本,不返回前一个片段的文本。

returnFinishInfoboolN

音频流结束回调通知

可选值(默认为false):
false:审核结束时不发送结束通知

true:审核结束时发起结束通知,回调参数增加statCode状态码

initDomainintN当即构客户端init初始化支持隔离域名和随机userId该字段必传,可选值:
1:仅支持客户端初始化有隔离域名
2:支持客户端初始化有隔离域名和随机userId功能名
audioDetectStepintN音频每个步长只会检测一次,取值范围1-5的整数,默认每个片段都审核(备注)

其中data.agoraParam内容如下:

参数名称类型是否必选说明
appIdstringY声网提供的appId,注意与数美的appId区分开
channelstringY声网提供的频道名,注意与数美channel区分开。
tokenstringN

安全要求较高的用户可以使用 Token进行认证,生成方式详见声网文档: https://docs.agora.io/cn/Interactive%20Broadcast/token_server?platform=All%20Platforms

数美建议token最小有效期为15分钟以上

uidintN用户 ID,32 位无符号整数。当token存在时,必须提供生成token时所使用的用户ID。注意,此处需要区别实际房间中的用户uid,提供给服务端录制所用的uid不允许在房间中存在。
isMixingEnabledboolN

单流/合流录制,默认合流录制。

true:合流

false:分流

合流是指一个直播房间一路流,分流是指一个麦位一路流

channelProfileintN

声网录制的频道模式,取值:

0: 通信(默认),即常见的 1 对 1 单聊或群聊,频道内任何用户可以自由说话;

1: 直播,有两种用户角色: 主播和观众。

默认以通信模式录制,即默认值为0。

renewTokenURLstringN

用于更新声网Token的接口,详见更新声网Token接口规范

如果不提供该参数,则不会更新Token,当Token失效时就该声网流无法继续审核

其中data.zegoParam内容如下

参数名称类型是否必选说明
tokenIdstringYzego提供的身份验证信息,用于token登陆
streamIdstringY用户设置的音频流编号,唯一对应一路音频流,streamId与roomId至少存在其中之一,如果streamId与roomId同时存在时,streamId有效;当streamId生效时,服务端以用户为单位拉流。
roomIdstringY用户设置的房间编号,唯一对应一个房间,streamId与roomId至少存在其中之一,如果streamId与roomId同时存在时,streamId有效;当roomId生效时,服务端以房间为单位拉流。
testEnvboolY是否使用zego测试环境,指定true时为测试环境,指定false时为正式环境。默认为false

其中 data.trtcParam内容如下

参数名称类型是否必选说明
sdkAppIdintY腾讯提供的sdkAppId
demoSencesintY

录制类型可选值:

分流录制:2
合流录制:4

userIdstringY分配给录制段的userId,限制长度为32bit,只允许包含(a-zA-Z),数字(0-9)以及下划线和连词符
userSigstringY录制userId对应的验证签名,相当于登录密码
roomIdintY

房间号码,取值范围:【1-4294967294】

roomId与strRoomId必传一个,若两者都有值优先选用roomId

strRoomIdstringY

房间号码
取值说明:只允许包含(a-zA-Z),数字(0-9)以及下划线和连词符

若您选用strRoomId时,需注意strRoomId和roomId两者都有值优先选用roomId

返回参数#

放在HTTP Body中,采用Json格式,具体参数如下:

参数名称类型是否必选说明
codeintY返回码
messagestringY返回码详情描述
requestIdstringY请求唯一标识
detailjson_objectN描述详细信息

detail结构如下:

参数名称类型是否必选说明
errorCodeintY状态码

errorCode对应说明如下:

codemessage
1001重复推流

回调策略#

当用户收到推送结果,并返回HTTP状态码为200时,表示推送成功;否则

系统将进行最多12次推送。

请求方法#

POST

字符编码格式#

请求及返回结果都使用UTF-8字符集进行编码

回调参数#

放在HTTP Body中,采用Json格式,具体参数如下:

参数名称类型是否必选说明
codeintY返回码
messagestringY返回码详情描述
requestIdstringY请求唯一标识
scoreintN

风险分数(code 为 1100 且riskLevel=REJECT时存在)

取值范围[0,1000],分数越高风险越大

riskLevelstringY

风险级别(code 为 1100 时存在)

可能返回值:PASS,REVIEW,REJECT

PASS:正常内容,建议直接放行

REVIEW:可疑内容,建议人工审核

REJECT:违规内容,建议直接拦截

statCodeintN

审核状态:

0 :审核中:

1 :审核结束

detailjson_objectY风险详情

其中,detail 的内容如下:

参数名称类型是否必选说明
beginProcessTimeintY开始处理的时间(13位时间戳)
finishProcessTimeintY结束处理的时间(13位时间戳)
audioUrlstringY

音频片段地址,returnAllText不传或为false时只返回违规音频片段地址,

returnAllText为true时返回所有音频片段地址

preAudioUrlstringN违规内容前一个10秒音频片段地址(该参数只有在请求参数中returnPreAudio是true情况下存在)
audio_endtimestringY违规内容结束时间(绝对时间)
audio_starttimestringY违规内容开始时间(绝对时间)
audioTextstringY音频片段文本
contentstringNreturnPreText为true时返回违规内容前一个片段10秒文本和违规内容片段文本
descriptionstringY策略规则风险原因描述
注:该参数为旧版 API 返回参数,兼容保留,
后续版本将去除,请勿依赖此参数,仅供参考
descriptionV2stringY策略规则风险原因描述
注:该参数为 API 返回参数
请勿依赖此参数,仅供参考
matchedItemstringN命中的具体敏感词(该参数仅在命中敏感词时存在)
matchedListstringN命中敏感词所在的名单名称(该参数仅在命中
敏感词时存在)
hitsjson_arrayY展示风险详情,请勿依赖此参数,仅供参考
modelstringY规则标识,用来标识文本命中的策略规则。
注:该参数为旧版 API 返回参数,兼容保留,
后续版本将去除,请勿依赖此参数,仅供参考
isSingintNtype取值包含SING时存在,取值0表示检测不存在唱歌片段,取值1表示检测存在唱歌片段
requestParamsjson_objectY返回请求参数data中的所有字段
riskTypeintY

标识风险类型,可能取值:
风险类型,静音时不返回,可能取值:
0:正常

100:涉政

110:暴恐

120:国歌

200:色情

210:辱骂

250:娇喘

260:一号领导声纹

270:人声属性

280:违禁歌曲

300:广告

400:灌水

500:无意义

520:未成年人

600:违禁

700:其他

720:黑账号

730:黑IP

800:高危账号

900:自定义

riskTypeDescstringN风险原因描述
roomstringY房间号
userIdintN用户账号标识(仅分流情况下存在)。返回的userId是实际房间中的用户id,与请求参数中的uid无关。
strUserIdstringN用户账号标识(仅TRTC分流情况下存在)。返回的userId是实际房间中的用户id,与请求参数中的uid无关。
vadCodeintN

静音状态:

0 :静音片段

1 :非静音片段

seiInfoarrayN

(需要联系数美开通)

展示流片段插入的SEI信息

languagejson_arrayN语种识别与概率值列表,在type下传入返回。
minorLabelintN

当type传入MINOR且命中未成年人标签时,才会返回;

1:未成年人

businessLabelsjson_arrayY音频业务标签返回
riskSourceintY

风险来源

1000:无风险

1001:文字

1003:音频

detail.language数组中每一项具体参数如下:

参数名称类型是否必选说明
labelintY

语种识别类别标识,可能取值:

0:普通话

1:英语

2:粤语

confidenceintY对应语种标签可能性大小,取值0-100,数值越高表示概率越大。

其中,businessLabels详细内容如下:

参数名类型参数说明是否必返备注
businessLabel1string一级业务标签
businessLabel2string二级业务标签
businessLabel3string三级业务标签
businessDescriptionstring业务标签描述中文标签描述

code和message的列表如下:

Codemessage
1100成功
1902参数不合法
1903服务失败
9100余额不足
9101无权限操作

示例#

请求示例#

curl 'http://api-audiostream-bj.fengkongcloud.com/v2/saas/anti_fraud/audiostream' -d'{
"accessKey": "",
"type": "LANGUAGE",
"appId": "default",
"btid": "",
"callback": "http://10.141.16.179:8900/",
"data": {
"streamType": "TRTC",
"trtcParam": {
"sdkAppId": 1400498247,
"demoSences": 4,
"userId": "12345",
"userSig": "",
"roomId": 517067780
},
"returnPreText": true,
"returnPreAudio": true,
"tokenId": "shumei-test",
"channel": "",
"returnAllText": true,
"callbackParam": {
"test1": 1,
"test2": "qew",
"test3": true
},
}
}'

返回示例#

{
"code":1100,
"message":"成功",
"requestId":" a78eef377079acc6cdec24967ecde722"
}

回调接口返回的内容示例#

{
"code": 1100,
"message": "成功",
"requestId": "a78eef377079acc6cdec24967ecde722_12345_0",
"riskLevel": "REJECT",
"detail": {
"audioUrl": "[http://xxxx.mp3](http://xxxx.mp3/)",
"preAudioUrl": "[http://prexxxx.mp3](http://prexxxx.mp3/)",
"audio_endtime": "2018-09-18 17:54:31",
"audio_starttime": "2018-09-18 17:54:21",
"content": "啥鸡巴破地方啊,我发现我进传销了,兄弟们跟我过来当老板",
"description": "色情内容",
"matchedItem": "鸡巴",
"matchedList": "色情",
"model": "M1020_20",
"requestParams":{
"streamType": "TRTC",
"trtcParam": {
"sdkAppId": 1400498247,
"demoSences": 4,
"userId": "12345",
"userSig": "",
"roomId": 517067780
},
"returnPreText": true,
"returnPreAudio": true,
"tokenId": "shumei-test",
"channel": "",
"returnAllText": true,
"callbackParam": {
"test1": 1,
"test2": "qew",
"test3": true
},
},
"riskType": 200,
"riskTypeDesc": "色情",
"room": "16037880"
}
}

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格式,具体参数如下:

参数名称类型是否必选说明
accessKeystringY用于权限认证,开通账号服务时由数美提供
requestIdstringY关闭的音频流的requestId

返回参数#

放在HTTP Body中,采用Json格式,具体参数如下:

参数名称类型是否必选说明
codeintY返回码
messagestringY返回码详情描述
requestIdstringY请求唯一标识

code和message的列表如下:

Codemessage
1100成功
1902参数不合法
1903服务失败
9100余额不足
9101无权限操作或accessKey错误

示例#

请求示例#

curl 'http://api-audiostream-sh.fengkongcloud.com/v2/saas/anti_fraud/finish_audiostream' -d'{
"accessKey": "xxxxx",
"requestId": "yyyy"
}'

返回示例#

{
"code":1100,
"message":"成功",
"requestId":" a78eef377079acc6cdec24967ecde722"
}

3.更新声网Token接口规范#

声网的Token存在有效期,过期后需要更新Token,详见:

https://docs.agora.io/cn/Agora%20Platform/channel_key

https://docs.agora.io/cn/All/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_constants.html#ac7ed64c7dc79350210daef29296d28dc

当声网的Token失效时,数美会根据客户提供的renewTokenURL接口获取更新后的Token。

为了统一,该接口需要满足以下规范:

请求方式#

POST

请求参数#

至少会携带以下字段:

参数名称类型是否必填说明
requestIdstringY开启审核时的requestId
streamTypestringY返回码详情描述
datajson_objectY在请求更新Token接口时,会携带客户开启审核时的部分参数

data字段结构:

参数名称类型是否必填说明
agoraParamjson_objectY与客户当时开启审核时传的参数一致,详见开启审核接口中的data.agoraParam

返回结果#

至少需要返回以下字段:

参数名称类型是否必填说明
codeintY0为成功,非0代表失败
msgstringY

code为0时:成功

code非0时:具体失败原因

tokenstringY

更新后的声网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等所有主流网络协议。

在线咨询