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

版权所有，翻版必究

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-web-bj.fengkongcloud.com/saas/monthBill/v1

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证，由数美提供是
startMonthstring开始月份，如：2019-10是
endMonthstring结束月份，如：2019-11是
actionstring默认值：list否

输入示例

{
"action": "list",
"accessKey": "xxxxxx",
"startMonth": "2019-09",
"endMonth": "2019-10"
}

输出参数

字段类型说明是否必须
codeint状态码，1100 成功，其他失败是
messagestring提示语是
sumFeefloat总消耗，单位：元是
contentsobject_array数组是

contents 中的子参数：

字段类型说明是否必须
monthstring月份，如：2019-11是
feeTypestring计费类型，查询、类型、包年等是
feefloat消耗金额，单位元，两位小数是
productNamestring产品名称是
appNamestring应用名称，不区分时值为：-是
feeDetailobject_array计费详情是

feeDetail 中的子参数：

字段类型说明是否必须
pricefloat单价，单位：元是
countint调用次数是
typestring功能类型，当计费方式类型时返回否

输出示例

{
"code": 1100,
"message": "成功",
"contents": [
{
"month": "2019-10",
"feeType": "包年",
"fee": 0,
"feeDetail": [
{
"price": 0,
"count": 1
}
],
"productName": "天净-智能文本识别",
"appName": "-"
},
{
"month": "2019-10",
"feeType": "包年",
"fee": 0,
"feeDetail": [
{
"price": 0,
"count": 1
},
{
"price": 2,
"count": 2,
"type": "语音内容"
}
],
"productName": "xxxxxxxx",
"appName": "-"
}
],
"sumFee": 1.14
}

2.3. 查询日账单明细#

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

请求方法 POST

输入参数

字段类型说明是否必须
accessKeystring用于权限认证，由数美提供是
startDaystring开始日期，如：2019-10-01是
endDaystring结束日期，如：2019-11-01是
actionstring默认值：list否
appIdstring用以筛选应用，不传展示所有否

输入示例

{
"action": "list",
"accessKey": "xxxxxx",
"startDay": "2019-09-01",
"endDay": "2019-10-02",
"appId": "default"
}

输出参数

字段类型说明是否必须
codeint状态码，1100 成功，其他失败是
messagestring提示语是
sumFeefloat总消耗，单位：元是
contentsobject_array数组是

contents 中的子参数：

字段类型说明是否必须
daystring日期，如：2019-11-01是
feefloat消耗金额，单位元，两位小数是
feeTypestring计费类型，查询、类型、包年等是
productNamestring产品名称是
appNamestring应用名称，不区分时为：-是
feeDetailobject_array计费详情是

feeDetail 中的子参数：

字段类型说明是否必须
pricefloat单价，单位：元是
countint调用次数是
typestring功能类型，当计费方式类型时返回否

输出示例

{
"code": 1100,
"message": "成功",
"contents": [
{
"day": "2019-11-01",
"feeType": "包年",
"fee": 0,
"feeDetail": [
{
"price": 0,
"count": 1
}
],
"productName": "天净-智能文本识别",
"appName": "-"
},
{
"day": "2019-11-01",
"feeType": "包年",
"fee": 0,
"feeDetail": [
{
"price": 0,
"count": 2
}
],
"productName": "天网-注册登录保护",
"appName": "-"
},
{
"day": "2019-11-01",
"feeType": "类型",
"fee": 1.94,
"feeDetail": [
{
"count": 3,
"type": "娇喘",
"price": 1
},
{
"price": 2,
"count": 3,
"type": "语音内容"
},
{
"price": 0,
"count": 3,
"type": "音色标签"
}
],
"productName": "天净-智能音频识别",
"appName": "-"
},
{
"day": "2019-11-01",
"feeType": "查询",
"fee": 1234,
"feeDetail": [
{
"price": 123,
"count": 2
}
],
"productName": "天净-智能图片识别",
"appName": "-"
}
],
"sumFee": 57
}

2.4. 名单相关接口#

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

建议 QPS < 20

2.4.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.4.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.4.3. 删除名单#

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

请求方法 POST

输入参数

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

输入示例

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

输出参数

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

输出示例

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

2.4.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.4.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.4.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.4.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.4.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.4.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正则匹配
7天免费试用

  • 专属顾问全程服务

  • 个性化制定解决方案

  • 全天候响应问题随时解决

在线咨询

京公网安备 11010502032103号 | 京ICP备15044177号

Copyright©2015-2024 shumei All Rights Reserved