数美对外开放接口使用手册#


版权所有,翻版必究


1. 文档目标#

提供数美对外开放接口的说明

2. 接口说明#

  • 接口访问凭证 accessKey 是每次调用接口必带参数,要求放到 Request-Body 中
  • Request-Body 中必须是标准的 Json 格式
  • 请求及返回结果都使用 UTF-8 字符集进行编码

2.1. 查询账户余额#

请求 URL https://api-web-bj.fengkongcloud.com/saas/balance/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供

输入示例

{
"accessKey": "xxxxx"
}

输出参数

字段类型说明是否必须
codeint状态码,1100 成功,其他失败
messagestring提示语
contentobject数据对象

content 中的子参数:

字段类型说明是否必须
balancefloat余额,单位:元

输出示例

{
"code": 1100,
"message": "成功",
"content": {
"balance": 1357.65
}
}

2.2. 查询账单明细#

请求 URL https://api-operation-bj.fengkongcloud.com/api/bill/get

请求方法 POST

输入参数

说明: 对外api使用Accesskey(参数key为X-Accesskey)方式验证,每次请求需在HTTP请求头Header中携带此参数。

请求Header参数如下:

参数名称类型是否必选说明
X-Accesskeystring用于权限认证,开通账号服务时由数美提供

请求其他参数放在HTTP Body中,具体参数如下:

参数名称类型是否必选说明
organizationstring公司标识
datestring时间 示例:2023-10

输入示例

{
"organization":"xxxxx",
"date":"2023-10"
}

输出参数

参数名称类型说明
codeint返回码
1100:成功
1902: QPS超限
1902: 参数不合法
1903: 服务异常
messagestring返回码详情描述
contentobject账单数据列表

content 字段如下所示:

参数名称类型说明
namestring公司简称
fullNamestring公司全称
totalPricefloat总金额 精度为小数点后2位
writeOffPricefloat核销金额 精度为小数点后2位
couponPricefloat优惠券金额 精度为小数点后2位
cashPricefloat现金金额 精度为小数点后2位
monthlyStatementobject月账单

monthlyStatement 是一个对象,key-value结构,key是产品标识,value中的字段如下

参数名称类型说明
requestCountobject请求量
请求量为用户请求api的量级,一次请求记1。音频流的requestCount为截取的音频片段数量。
requestDurationobject请求音频时长
请求音频时长为客户请求的音频类数据的总时长
billarray月账单明细

requestCount字段如下所示

参数名称类型说明
countint请求量
unitstring单位

requestDuration字段如下所示

参数名称类型说明
durationint请求时长
unitstring单位

bill 字段如下所示

参数名称类型说明
datestring日期:年-月
productstring产品
appNamestring应用名称
functionNamestring功能
unitPricefloat单价 精度为小数点后6位
priceUnitstring计费单位
countfloat调用量 精度为小数点后4位
调用量为调用模型的次数,是真实的计费量,和请求量有区别。例如图片会按照截帧图计费,一张图如果被截了2张截帧图,请求量计1,调用量计2。
unitstring调用量单位
pricefloat总金额 精度为小数点后2位
dailyStatementarray日账单

dailyStatement字段如下所示

参数名称类型说明
datestring日期:年-月-日
productstring产品
appNamestring应用名称
functionNamestring功能
unitPricefloat单价 精度为小数点后6位
priceUnitstring计费单位
countfloat调用量 精度为小数点后4位
unitstring调用量单位
pricefloat计费金额 精度为小数点后2位

输出示例

{
"code": 1100,
"message": "success",
"content": {
"name": "xxxx",
"fullName": "xxxxx",
"totalPrice": 559.35,
"writeOffPrice": 0,
"couponPrice": 0,
"cashPrice": 559.35,
"monthlyStatement": {
"POST_AUDIOSTREAM_EN": {
"requestCount": {
"count": 5409487763,
"unit": "次"
},
"requestDuration": {
"duration": 5409487763,
"unit": "秒"
},
"bill": [
{
"date": "2023-12",
"product": "智能语义-智能音频流识别(英语)",
"appName": "默认应用",
"functionName": "娇喘",
"unitPrice": 0.01,
"priceUnit": "元/小时",
"count": 49339.3514,
"unit": "小时",
"price": 493.39,
"dailyStatement": [
{
"date": "2023-12-31",
"product": "智能语义-智能音频流识别(英语)",
"appName": "默认应用",
"functionName": "娇喘",
"unitPrice": 0.01,
"priceUnit": "元/小时",
"count": 49339.3514,
"unit": "小时",
"price": 493.39
}
]
}
]
},
"POST_IMG": {
"requestCount": {
"count": 157690,
"unit": "次"
},
"requestDuration": {
"duration": 0,
"unit": "秒"
},
"bill": [
{
"date": "2023-12",
"product": "智能视觉-智能图片识别",
"appName": "默认应用",
"functionName": "图片文字违规识别",
"unitPrice": 1.5,
"priceUnit": "元/万张",
"count": 15.7691,
"unit": "万张",
"price": 23.65,
"dailyStatement": [
{
"date": "2023-12-31",
"product": "智能视觉-智能图片识别",
"appName": "默认应用",
"functionName": "图片文字违规识别",
"unitPrice": 1.5,
"priceUnit": "元/万张",
"count": 15.7691,
"unit": "万张",
"price": 23.65
}
]
}
]
},
"POST_VIDEO": {
"requestCount": {
"count": 282049,
"unit": "次"
},
"requestDuration": {
"duration": 0,
"unit": "秒"
},
"bill": [
{
"date": "2023-12",
"product": "天净-智能视频文件识别",
"appName": "默认应用",
"functionName": "截帧图片色情&性感",
"unitPrice": 1.5,
"priceUnit": "元/万次",
"count": 28.2049,
"unit": "万次",
"price": 42.31,
"dailyStatement": [
{
"date": "2023-12-31",
"product": "天净-智能视频文件识别",
"appName": "默认应用",
"functionName": "截帧图片色情&性感",
"unitPrice": 1.5,
"priceUnit": "元/万次",
"count": 28.2049,
"unit": "万次",
"price": 42.31
}
]
}
]
}
}
}
}

2.3. 名单相关接口#

数美内容识别服务支持自定义名单,通过名单结果查看、修改、增加、删减名单内容

建议 QPS < 20

2.3.1. 名单列表#

请求 URL https://webapi.fengkongcloud.com/saas/listService/list/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
typeint自定义类型:1,天网内置类型:4,文本、图片内置类型:5
serviceIdstring服务标识,取值见附录 3.5
checkItemsstring_array匹配字段,详情见附录 3.3
riskLevelstring处置建议,取值见附录 3.6
offsetint偏移量,非负整数,默认为 0
countint条目数,不大于 100 的正整数不传 count,默认值是:10

输入示例

{
"accessKey": "4Ky6AV4hE0pWLeG1bXNw",
"serviceId": "POST_TEXT",
"count": 20,
"offset": 0,
"type": 1,
"riskLevel": "REJECT",
"checkItems": ["text", "nickname"]
}

输出参数

字段类型说明是否必须
totalCountint总条数
contentsobject_array事件记录

contents 中的子参数:

字段类型说明是否必须
idstring名单编号
listIdString名单编号与 id 相同,兼容写法
namestring名单名字
ownerstring名单人
descriptionstring描述
createTimeint名单创建时间,毫秒时间
modifyTimeint名单修改时间
statusint启用状态
configobject配置内容
priorityint优先级
topLevelint是否置顶
itemCountInt名单内敏感词个数

config 中的子参数:

字段类型说明是否必须
actionstring处理方法,取值见 附录 3.7
checkItemsstring_array匹配字段,取值见附录 3.3
operationstring匹配方式,取值见附录 3.8
segmentStatusstring切词方式,取值:
"0":默认切词
"1":空格切词
riskTypeint风险原因,见附录 3.4
appIdstring生效应用

输出示例

{
"contents": [
{
"actionCN": "拒绝",
"appCN": "全部",
"channelCN": "全部",
"channelEventCN": "全部",
"checkItemsCN": ["文本内容", "昵称"],
"config": {
"action": "REJECT",
"appId": "",
"checkItems": ["text", "nickname"],
"operation": "contain",
"riskType": 300
},
"createTimeCN": "06-28 15:35:59",
"description": "",
"endTime": 315504000000,
"eventCN": "全部",
"itemCount": 0,
"listId": "0da5ad4f49c350ccdd79b94bf00d8a98",
"modifyTimeCN": "06-28 15:42:30",
"name": "更新后测试黑名单 3",
"operationCN": "原文匹配",
"owner": "0",
"priority": 0,
"riskTypeCN": "广告",
"risklabelCN": "",
"startTime": 315504000000,
"status": 1,
"topLevel": 0,
"type": 1
},
{
"actionCN": "拒绝",
"appCN": "全部",
"channelCN": "全部",
"channelEventCN": "全部",
"checkItemsCN": ["文本内容", "昵称"],
"config": {
"action": "REJECT",
"appId": "",
"checkItems": ["text", "nickname"],
"operation": "equal",
"riskType": 100,
"segmentStatus": "0"
},
"createTimeCN": "06-28 15:33:13",
"description": "",
"endTime": 315504000000,
"eventCN": "全部",
"itemCount": 0,
"listId": "ba231dc0759f599fdffce5464e344632",
"modifyTimeCN": "06-28 15:33:13",
"name": "更新后文本黑名单 2",
"operationCN": "相等匹配",
"owner": "0",
"priority": 0,
"riskTypeCN": "涉政",
"risklabelCN": "",
"startTime": 315504000000,
"status": 1,
"topLevel": 0,
"type": 1
}
],
"totalCount": 133
}

2.3.2. 新增名单#

请求 URL https://webapi.fengkongcloud.com/saas/listService/add/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstring名单 Id,MD5 值,确保唯一
namestring名单名字,注意不能重复
serviceIdstring服务标识,取值见附录 3.5
descriptionstring描述
typeint自定义名单:1
configobject配置内容

config 中的子参数:

字段类型说明是否必须
actionstring处理方法,取值见附录 3.7
checkItemsobject_array匹配字段,取值见附录 3.3
operationstring匹配方式,取值见附录 3.8
segmentStatusstring切词方式,取值:
"0":默认切词
"1":空格切词
riskTypeint风险原因,取值范围见附录 3.4,
appIdstring生效应用
eventIdstring生效事件
filterobject名单生效的条件

filter 中的子参数:

字段类型说明是否必须
channelstring渠道生效范围,多个 | 分割,如:aa|bb

输入示例

{
"name": "后端测试",
"status": 1,
"listId": "2b2bd7fab89ce92688417ba18ba5d458",
"priority": 0,
"config": {
"checkItems": ["text"],
"action": "PASS",
"appId": "",
"riskType": 710,
"operation": "equal"
},
"contents": "",
"contentRemarks": [],
"subType": "text",
"organization": "RlokQwRlVjUrTUlkIqOg",
"product": "POST_AUDIO",
"type": 1
}

输出参数

字段类型说明是否必须
codeint返回码,值为 1100 表示成功,其他失败
messagestring详细描述

输出示例

{
"code": 1100,
"message": "请求成功"
}

2.3.3. 删除名单#

请求 URL https://webapi.fengkongcloud.com/saas/listService/delete/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
idsarray要删除的名单号列表

输入示例

{
"accessKey": "xxxxxxxxxxxxxxx",
"ids": ["424fd492cc4f6f0432cfb230a6ab7341"]
}

输出参数

字段类型说明是否必须
codeint返回码,1100 成功,其他失败
messagestring详细描述

输出示例

{
"code": 1100,
"message": "请求成功"
}

2.3.4. 修改名单#

请求 URL https://webapi.fengkongcloud.com/saas/listService/update/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstring名单 Id,保证之前新增的时候指定的 id 一致
namestring名单名字
descriptionstring描述
configobject配置内容
statusint启用状态,0:禁用,1:启用

config 中的子参数:

字段类型说明是否必须
actionstring处理方法,取值见附录 3.7
checkItemsobject_array匹配字段,取值见附录 3.3
operationstring匹配方式,取值见附录 3.8
segmentStatusstring切词方式,取值:
"0":默认切词
"1":空格切词
riskTypeint风险原因,取值见附录 3.4
appIdstring生效应用
eventIdstring生效事件
filterobject名单生效的条件

filter 中的子参数:

字段类型说明是否必须
channelstring渠道生效范围,多个 | 分割,如:aa|bb

输入示例

{
"listId": "424fd492cc4f6f0432cfb230a6ab7341",
"name": "sjx01",
"status": 1,
"type": 1,
"description": "",
"config": {
"action": "REJECT",
"appId": "",
"checkItems": ["phone"],
"ignoreStatus": "0",
"operation": "equal"
},
"serviceId": "P_TIAN_WANG",
"accessKey": "4Ky6AV4hE0pWLeG1bXNw"
}

输出参数

字段类型说明是否必须
codeint返回码,1100 成功,其他失败
messagestring详细描述

输出示例

{
"code": 1100,
"message": "请求成功"
}

2.3.5. 名单内容列表#

请求 URL https://webapi.fengkongcloud.com/saas/listService/contentList/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstrig名单 md5 的 id
offsetint偏移量,默认值为 0,取值为非负整数
countint条目数,不大于 100 的正整数

输入示例

{
"count": 10,
"offset": 0,
"listId": "424fd492cc4f6f0432cfb230a6ab7341",
"accessKey": "4Ky6AV4hE0pWLeG1bXNw"
}

输出参数

字段类型说明是否必须
codeint1100 成功,其他失败
messagestring提示语
totalCountint总条数
contentsobject_array事件记录

contents 中的子参数:

字段类型说明是否必须
contentstring内容
operateTimestring操作时间,如:”1544151689453”
remarksstring备注
countint命中次数
operatorstring操作人

输出示例

{
"code": 1100,
"message": "成功",
"contents": [
{
"content": "dsf",
"data": "dsf",
"operateTime": "1575865083959",
"remarks": "",
"count": 0,
"operator": "liu@ishumei.com"
},
{
"content": "dd",
"data": "dd",
"operateTime": "1575864414464",
"remarks": "",
"count": 0,
"operator": "liu@ishumei.com"
}
],
"totalCount": 2
}

2.3.6. 新增名单内容#

建议 QPS:同一名单 < 100;不同名单 < 20

请求 URL https://webapi.fengkongcloud.com/saas/listService/contentAdd/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstring名单 listId md5 值
contentsobject_array内容数组
remarksobject_array内容数组,备注信息,默认备注信息接口调用
operatorstring操作人,用于记录操作日志
serviceIdstring服务标识,需与名单一致
checkItemsobject_array匹配字段

输入示例

{
"accessKey": "xxx",
"listId": "9d3bf5b1ab175bcce1dd73423b17b45a",
"serviceId": "P_TIAN_WANG",
"contents": ["test"],
"remarks": ["test"],
"operator": "XXX",
"batchRemarks": 1
}

输出参数

字段类型说明是否必须
codeint返回码,1100 成功,其他失败
messagestring详细描述

输出示例

{
"code": 1100,
"message": "请求成功"
}

2.3.7. 删除名单内容#

建议 QPS:同一名单 < 100;不同名单 < 20

请求 URL https://webapi.fengkongcloud.com/saas/listService/contentDelete/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstring名单 listId md5 值
contentsobject_array内容数组,非图片服务
operatorstring操作人,用于记录操作日志
serviceIdstring服务标识,取值需要与名单一致

输入示例

{
"listId": "bc426e21a9f55bab787789c2d2a131f3",
"accessKey": "4Ky6AV4hE0pWLeG1bXNw",
"serviceId": "POST_TEXT",
"operator": "xxx.@ishumei.com",
"contents": ["测试"]
}

输出参数

字段类型说明是否必须
codeint返回码,1100 成功,其他失败
messagestring详细描述

输出示例

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

2.3.8. 修改名单内容#

请求 URL https://webapi.fengkongcloud.com/saas/listService/contentUpdate/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
listIdstring名单 listId md5 值
newContentstring待更新内容
oldContentstring修改前内容
remarkstring备注,默认备注信息接口调用
operatorstring操作人,用于记录操作日志
serviceIdstring服务标识,取值与名单一致

输入示例

{
"accessKey": "4Ky6AV4hE0pWLeG1bXNw",
"listId": "424fd492cc4f6f0432cfb230a8ab7341",
"serviceId": "POST_IMG",
"operator": "xxx.@ishumei.com",
"oldContent": "123",
"newContent": "456",
"remark": ""
}

输出参数

字段类型说明是否必须
codeint返回码,1100 成功,其他失败
messagestring详细描述

输出示例

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

2.3.9. 名单内容检索#

请求 URL https://webapi.fengkongcloud.com/saas/listService/contentSearch/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证,由数美提供
countint条目数,不大于 100 的正整数
offsetint偏移量,非负整数,默认为 0
serviceIdstring服务标识,取值与名单一致
appIdstring生效应用
contentstring检索敏感词

输入示例

{
"accessKey": "4Ky6AV4hE0pWLeG1bXNw",
"serviceId": "POST_IMG",
"offset": 0,
"count": 2,
"content": "test"
}

输出参数

字段类型说明是否必须
codeint1100 成功,其他失败
messagestring提示语
totalCountint总条数
contentsobject_array内容列表

contents 中的子参数:

字段类型说明是否必须
contentstring内容
hitListIdstring名单 md5 id
hitConfigNamestring名单名称
hitConfigConfigobject名单配置

输出示例

{
"code": 1100,
"message": "成功",
"contents": [
{
"content": "testtest",
"hitItemId": null,
"hitItemOwner": null,
"hitItemCreateTime": null,
"hitItemContent": "testtest",
"hitListId": "585c0dbb2924f53bb90971423c2c577e",
"action": null,
"hitConfigName": "ocr 黑名单 11",
"hitConfigOwner": "",
"hitConfigConfig": {
"action": "REJECT",
"appId": "",
"channelValid": "1",
"checkItems": ["text"],
"classDescription": "",
"filter": [],
"ignoreStatus": "0",
"operation": "equal",
"riskType": "100"
},
"hitConfigDescription": "",
"hitConfigCreateTime": null,
"hitConfigModifyTime": 0,
"hitConfigType": 1,
"hitConfigStartTime": 0,
"hitConfigEndTime": 0,
"hitConfigStatus": 1,
"isGlobal": 0,
"sort": 1
}
],
"totalCount": 2
}

3. 附录#

3.1. 事件列表#

服务中文标识中文解释
天网POST_EVENT业务事件
^ACCOUNT_LOGIN登录
^ACCOUNT_REGISTER注册
^ANTI_ROBOT_MARKETING羊毛党
^ANTI_ROBOT_SMS短信保护通道
^SVERIFY_CAPTCHA验证码
天净POST_TEXT智能文本
^POST_IMG智能图片
^POST_AUDIO智能音频
^POST_AUDIOSTREAM智能音频流
^POST_VIDEO智能视频
^POST_VIDEOSTREAM智能视频流
^POST_ARTICLE智能网页

3.2. 名单返回码#

类别返回码原因解决方式
通用-1参数错误检查传入参数,是否有漏传或丢包。
^-11Config串错误 检查 config 串,是否传入了非法字段
添加词条-19名单不存在检查 listId 以及名单名称 name
^-20名单已满删除部分无用词条
^-21添加词条全部重复传入的词条在名单中全部已经存在
^-22添加词条部分重复传入的词条在名单中部分已经存在(未存在的部分会被成功添加)
^-23名单不存在,获取名单失败检查传入的名单 id 是否正确,检查日志中的 SQL 语句是否正常
^-24修改后名单写入数据库失败检查数据库连接检查日志中的语句
添加名单-25名单已存在更换名单 id 或名单组织号、服务 id、名称三者之一。
^-26配置信息格式错误检查入参格式
^-27时间类型错误检查时间类型
^-29写入失败参考-24
删除词条-31传入为空检查传入的待删除词的数量
^-32名单不存在,读取名单失败检查传入名单 id 是否正确,检查 SQL 连接
^-34写入失败参考-29
删除名单-35传入为空检查传入的 id
^-39写入失败参考-34
修改词条-41名单不存在检查传入名单 id 是否正确
^-42词条不存在检查词条是否正确
^-44写入失败参考-39
修改名单-49写入失败参考-44
获取名单-51读取失败参考-32-2
^-52名单不存在检查传入的 id
检索文本-55读取数据库失败参考-51
查找名单-61读取失败参考-55
查找词条-65名单不存在检查传入的 id
^-66名单被破坏检查该 id 对应的数据库 value
其他-99未知错误-

3.3. 匹配字段#

标识中文名称
ipIP
tokenId账号
deviceId设备
smid服务端设备标识
phone手机号
text文本内容
nickname昵称
img图片内容
img_md5图片 MD5 值
text_md5文本 MD5 值
origin_md5原始 MD5 值
rejectNames涉政人脸
reviewNames疑似涉政人脸
qr_content二维码识别内容
email邮箱
receiveTokenId接收者账号
ipColumnIP 段(C 类)

3.4. 风险类型#

不同产品之间有差异,具体参考历史记录和页面的可选范围

风险类型中文解释
0正常
100涉政
110暴恐
200色情
210辱骂
250娇喘
260一号领导声纹
270人声属性
280违禁歌曲
300广告
310二维码
320水印
340网络诈骗
400灌水
500无意义
510不良场景
520未成年人
530人脸
531人像
533颜值
534人脸比对
535公众人物
540物品
541动物
542植物
550场景
560行业违规
570画面属性
600违禁
700其他
710白名单
720黑账号
730黑 IP
800高危账号
900自定义

3.5. serviceId#

服务标识
智能文本识别POST_TEXT
智能图片识别POST_IMG
智能视频文件识别POST_VIDEO
智能音频文件识别POST_AUDIO
智能视频流识别POST_VIDEOSTREAM
智能音频流识别POST_AUDIOSTREAM
业务事件POST_EVENT
机器登录识别ACCOUNT_LOGIN
机器登录注册ACCOUNT_REGISTER
羊毛党防刷ANTI_ROBOT_MARKETING
短信通道保护ANTI_ROBOT_SMS
智能验证码SVERIFY_CAPTCHA

3.6. 处置建议#

标识解释
PASS通过
REVIEW审核
REJECT拒绝
VERIFY二次验证
SLIDER_CAPTCHA滑动验证码
SELECT_CAPTCHA点选验证码
IGNORE忽略
EXCLUDE放行

3.7. action#

标识解释
PASS通过
REJECT拒绝
REVIEW审核
IGNORE忽略
EXCLUDE放行
REGEX_IGNORE正则忽略

3.8. operation#

标识解释
equal相等匹配
contain原文匹配
word语义匹配
variant变体名单
pinyin同音名单
like相似名单
image_hash相似匹配
regex正则匹配

在线咨询