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

智能音频流识别产品API文档
1. 接入前准备
2. 智能音频流过滤服务接口说明
3. FAQ

版本

版本号	更新时间	作者	更新说明
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

建议超时时长#

通用请求参数#

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

参数名称	类型	是否必选	说明
accessKey	string	Y	服务密钥，开通账号服务时由数美提供
type	string	N	识别类型，可选值： PORN：色情识别 ABUSE: 辱骂识别 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	流类型:可选择：流地址：NORMAL 声网录制：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）： 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 合流录制：4
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	房间号码取值说明：只允许包含（a-zA-Z），数字(0-9)以及下划线和连词符若您选用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	标识风险类型，可能取值: 风险类型，静音时不返回，可能取值: 0:正常 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，数值越高表示概率越大。

参数名称

类型

是否必选

说明

label

int

语种识别类别标识，可能取值：

0:普通话

1:英语

2:粤语

confidence

int

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

其中，businessLabels详细内容如下：

参数名	类型	参数说明	是否必返	备注
businessLabel1	string	一级业务标签	否
businessLabel2	string	二级业务标签	否
businessLabel3	string	三级业务标签	否
businessDescription	string	业务标签描述	否	中文标签描述

code和message的列表如下：

Code	message
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

建议超时时长#

请求参数#

放在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错误

示例#

请求示例#

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

请求参数#

至少会携带以下字段：

参数名称	类型	是否必填	说明
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分钟以上

参数名称

类型

是否必填

说明

code

int

0为成功，非0代表失败

msg

string

code为0时：成功

code非0时：具体失败原因

token

string

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