全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网

图片敏感人脸识别API

更新时间:2017-11-16 17:34:53

功能描述

​提取图片中的人脸信息.​​​

HTTP接口描述

公共描述

  • 云盾内容安全API调用的 域名公共请求查询参数公共请求头描述签名构造返回状态码等描述统一收录在 调用方式 章节。请务必阅读完 调用方式 章节后,在阅读本章节后续内容,才能清楚如何构造HTTP请求从而使用内容安全检测API进行开发.

  • 如果您自己来编写程序构建HTTP请求,请务必先阅读完调用方式 所有章节 及本页1.1章节及以后章节内容,同时您也可以参考部分语言的第三方构造好的HTTP请求(https://help.aliyun.com/document_detail/49178.html?spm=5176.doc28427.6.587.3n1CVE),参考如何设置HTTP请求头、查询参数、签名构造。

  • 新版API经过全新设计更易使用,使用老版本SDK用户点击下载 老版文档

  • 云盾内容安全图片检测同时提供同步和异步图片检测接口。云盾内容安全的大部分图片请求会在1秒内返回结果,但在一些特殊场景(比如系统繁忙导致堆积严重,图片较大,含有OCR场景),耗时一般会多些。同步和异步允许的最长检测时间是有区别的。同步允许的最长检测时间是6秒;而异步则允许最长排队等待时间为2分钟。当超过该限制,仍然没有检测完毕时,系统会强制返回超时错误码。对于用户来说,如果实时性要求不高,可以选择异步。否则选择同步。同步调用也相对简单些。对于同步调用,用户需要注意设置的超时时间最好为6秒。

1.1 场景(scene)和分类(label)

​图片检测有不同的场景(scene),每个场景scene)对应不同的分类(label)。对应关系如下:​

场景(scene)中文名 场景(scene) 分类(label) 备注
图片人脸识别 sface normal 正常图片, 无人脸
图片人脸识别 sface sface 含人脸图片

​​​​

1.2 图片人脸识别同步检测 (uri: /green/image/scan)

检测图片中的人脸信息。请求body是一个JSON对象,字段说明如下:​

字段 类型 是否必须 说明
bizType 字符串 可选 业务类型,由调用方提供。根据配置,后端可根据该字段对请求做不同处理。属于高级用法
scenes 字符串数组 必须 字符串数组,场景定义参考1.1小节, 图片人脸识别识别的scene取值为:sface.图片检测支持多场景(scenes)一起检测, 比如对一张图片进行黄图、暴恐、人脸的同时识别,scenes为[“porn”, “terrorism”, “sface”], 其他更多图片检测场景同时检测类似添加.
tasks JSON数组 必选 JSON数组中的每个元素是一个图片检测任务结构体,参见下面Image表

​Image表:​

字段 类型 是否必须 说明
clientInfo JSON结构体 可选 客户端信息,参考[调用方式/公共请求参数/公共查询参数]小节中ClientInfo结构体描述。服务器会把[调用方式/公共请求参数/公共查询参数]小节中全局的clientInfo和这里的独立的clientInfo合并。独立的clientInfo优先级更高。
dataId 字符串 可选 调用者通常保证一次请求中,所有的dataId不重复
url 字符串 必选 待检测图像URL
time 整型 可选 图片创建/编辑时间,单位为ms

​返回body中的Data字段是JSON数组,每一个元素有如下字段:​

字段 类型 是否必须 说明
code 整型 必须 错误码,和http的status code一致
msg 字符串 必须 错误描述信息
dataId 字符串 可选 对应的请求中的dataId
taskId 字符串 必须 云盾内容安全服务器返回的唯一标识该检测任务的ID
url 字符串 必须 对应的请求中的url
results 数组 可选 当成功时(code == 200),该结果的包含一个或多个元素。每个元素是个结构体。参见下表。

​上表results中包含的元素说明:​

字段 类型 是否必须 说明
scene 字符串 必须 风险场景,和传递进来的场景对应
label 字符串 必须 该图片的分类,取值范围参考1.1小节
sfaceData 数组 可选 识别出来的人脸信息列表.
suggestion 字符串 必须 取值范围:[“pass”, “review”], pass:图片未识别到人脸,review:图片有识别到人脸需要关注;注意:sface场景中suggestion并非管控建议,仅用于区分图片中是否存在人脸。

​上表sfaceData中包含的元素说明:​

字段 类型 是否必须 说明
x 浮点数 必须 以图片左上角为坐标原点,人脸左上角到y轴距离
y 浮点数 必须 以图片左上角为坐标原点,人脸左上角到x轴距离
w 浮点数 必须 人脸宽度
h 浮点数 必须 人脸高度
faces 数组 可选 识别出来的人脸匹配的相似人物.

​上表faces中包含的元素说明:​

字段 类型 是否必须 说明
rate 浮点数 必须 相似概率
name 字符串 必须 相似人物的名称

请求body例子:

  1. {
  2. "scenes": ["sface"],
  3. "tasks": [
  4. {
  5. "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
  6. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  7. }
  8. ]
  9. }

​响应例子:​

  1. {
  2. "msg":"OK",
  3. "code":200,
  4. "data":[
  5. {
  6. "msg":"OK",
  7. "code":200,
  8. "dataId":"6f88a7c3-d18a-4a2f-ab93-862bdd2f3152",
  9. "results":[
  10. {
  11. "label":"sface",
  12. "scene":"sface",
  13. "sfaceData":[
  14. {
  15. "w":158.0,
  16. "h":158.0,
  17. "x":87.0,
  18. "y":49.0,
  19. "faces":[
  20. {
  21. "rate":68.11,
  22. "name":"刘xxx"
  23. }
  24. ]
  25. }
  26. ]
  27. }
  28. ],
  29. "taskId":"imgBC0yzpk4Zb4uvNRC9XpLy-1mZu0X",
  30. "url":"http://1.jpg"
  31. }
  32. ],
  33. "requestId":"E8141801-AFC2-427B-ABE7-B24CA4257E39"
  34. }

1.3 图片人脸识别异步检测 (uri: /green/image/asyncscan)

异步检测图片中的人脸信息。请求body是一个JSON对象,字段说明如下:​

字段 类型 是否必须 说明
bizType 字符串 可选 业务类型,由调用方提供。根据配置,后端可根据该字段对请求做不同处理。属于高级用法
scenes 字符串数组 必须 字符串数组,场景定义参考1.1小节, 图片人脸识别识别的scene取值为:sface.图片检测支持多场景(scenes)一起检测, 比如对一张图片进行黄图、暴恐、人脸的同时识别,scenes为[“porn”, “terrorism”, “sface”], 其他更多图片检测场景同时检测类似添加.
callback 字符串 可选 异步检测结果回调通知用户url;支持http/https。但该字段为空时,用户必须定时检索检测结果
seed 字符串 可选 随机字符串,该值会用于用户回调通知请求中签名;当含有callback时,该字段为必须。
tasks JSON数组 必选 JSON数组中的每个元素是一个图片检测任务结构体,最多支持100个,即100张图片的检测.参见下面Image表

​Image表:​

字段 类型 是否必须 说明
clientInfo JSON结构体 可选 客户端信息,参考[调用方式/公共请求参数/公共查询参数]小节中ClientInfo结构体描述。服务器会把[调用方式/公共请求参数/公共查询参数]小节中全局的clientInfo和这里的独立的clientInfo合并。独立的clientInfo优先级更高。
dataId 字符串 可选 调用者通常保证一次请求中,所有的dataId不重复
url 字符串 必须 待检测图像URL
time 字符串 可选 内容创建/编辑时间
interval 整型 可选 GIF图/长图检测专用。截帧频率,GIF图可理解为图片数组,每interval张图片抽取一张进行检测。只有该值存在时,才会对GIF进行截帧。长图同时支持长竖图和长横图。对长竖图,按照9:16(宽:高)来计算总图数,并进行切割。长横图会按照16:9(宽:高)来计算总图数,并进行切割。这里的interval指示后台检测时可按照该间隔跳着检测,以节省检测成本。
maxFrames 整型 可选 GIF图/长图检测专用。最大截帧数量。当interval*maxFrames小于该图片所包含的图片数量时,截帧间隔会自动修改为“该图片所包含的图片数/maxFrames”,以提高整体检测效果。默认值为100。

请求body例子:

  1. {
  2. "scenes": ["sface"],
  3. "tasks": [
  4. {
  5. "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
  6. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  7. }
  8. ]
  9. }

响应例子:

  1. {
  2. "code": 200,
  3. "msg": "OK",
  4. "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
  5. "data": [
  6. {
  7. "code": 200,
  8. "msg": "OK",
  9. "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
  10. "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
  11. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  12. }
  13. ]
  14. }

返回body中的Data字段是JSON数组,每一个元素有如下字段:​

字段 类型 是否必须 说明
code 整型 必须 错误码,和http的status code一致
msg 字符串 必须 错误描述信息
dataId 字符串 可选 对应的请求中的dataId
taskId 字符串 必须 云盾内容安全服务器返回的唯一标识该检测任务的ID
url 字符串 必须 对应的请求中的url

结果回调通知参数callback、seed使用说明:

如果设置了回调通知参数callback,被回调callback值,即一个http(s)协议接口的url, 需支持post方法, 传输数据编码采用utf-8,并且支持两个表单参数checksum和content, 系统将按以下描述的生成规则和格式设置checksum和content的值,调用您的callback接口返回检测内容。

约定:您服务端接收到我们推送的结果后,返回的http状态码为200时,我们视为推送成功,其他的http状态码均视为您接收失败,我们将进行最多16次推送的重试。

回调结果参数的生成规则和格式:

属性 值类型 说明
checksum String 由用户uid + seed + content拼成字符串,通过sha256算法生产. 为防篡改,您可(非必须)在获取到推送结果时按此算法生成字符串,与checksum做一次校验
content String JSON字符串格式, 请自行解析反转成json对象, content结果格式如下所述

注: 用户uid(账号ID),请在阿里云控制台上查询:https://account.console.aliyun.com/#/secure

content值内容格式:

  1. {
  2. "msg":"OK",
  3. "code":200,
  4. "dataId":"6f88a7c3-d18a-4a2f-ab93-862bdd2f3152",
  5. "results":[
  6. {
  7. "label":"sface",
  8. "scene":"sface",
  9. "sfaceData":[
  10. {
  11. "w":158.0,
  12. "h":158.0,
  13. "x":87.0,
  14. "y":49.0,
  15. "faces":[
  16. {
  17. "rate":68.11,
  18. "name":"刘xxx"
  19. }
  20. ]
  21. }
  22. ]
  23. }
  24. ],
  25. "taskId":"imgBC0yzpk4Zb4uvNRC9XpLy-1mZu0X",
  26. "url":"http://1.jpg"
  27. }

1.4 图片人脸识别异步检测结果查询接口 (uri: /green/image/results)

客户端定时轮询查询异步检测结果;建议查询间隔为30秒,最长不能超出1个小时,否则结果将会丢失。请求body是一个JSON数组,字段说明如下:

字段 类型 是否必须 说明
body JSON数组 必须 要查询的taskId列表。最大长度不超过1000.

​返回body中的Data字段是JSON数组,每一个元素有如下字段:​

字段 类型 是否必须 说明
code 整型 必须 错误码,和http的status code一致
msg 字符串 必须 错误描述信息
dataId 字符串 可选 对应的请求中的dataId
taskId 字符串 必须 云盾内容安全服务器返回的唯一标识该检测任务的ID
url 字符串 可选 对应的请求中的url
results 数组 可选 当成功时(code == 200),该结果的包含一个或多个元素。每个元素是个结构体。参见下表。

​上表results中包含的元素说明:​

字段 类型 是否必须 说明
scene 字符串 必须 风险场景,和传递进来的场景对应
label 字符串 必须 该图片的分类,取值范围参考1.1小节
sfaceData 数组 可选 识别出来的人脸信息列表.
suggestion 字符串 必须 建议用户处理,取值范围:[“pass”, “review”], pass:图片未识别到人脸,review:图片有有识别到人脸需要关注;注意:sface场景中suggestion不会有block取值。

​上表sfaceData中包含的元素说明:​

字段 类型 是否必须 说明
x 浮点数 必须 以图片左上角为坐标原点,人脸左上角的y轴距离
y 浮点数 必须 以图片左上角为坐标原点,人脸左上角的x轴距离
w 浮点数 必须 人脸宽度
h 浮点数 必须 人脸高度
faces 数组 可选 识别出来的人脸匹配的相似人物.

​上表faces中包含的元素说明:​

字段 类型 是否必须 说明
rate 浮点数 必须 相似概率
name 字符串 必须 相似人物的名称

SDK调用方式

2.1 各语言SDK

如果您使用java、python、php语言,我们官方提供了对应的sdk,直接使用sdk调用即可,sdk如何调用请点击以下对应开发语言的链接继续阅读。

java

php

python

其他语言

2.2 代码示例

或者您也可以直接下载各语言的调用代码示例和离线文档进行阅读, 离线代码调用示例下载地址如下:​

  1. 图片链接协议支持:http和https
  2. 图片格式支持: PNG,JPG,JPEG,BMP,GIF,WEBP
  3. 同步调用时图片大小限制为5M,异步调用时图片大小限制为20M,图片下载时间限制为3s内,如果下载时间超过3s返回下载超时;
  4. 图片像素建议不小于256*256,太小可能会影响识别效果
  5. 图片检测接口响应时间依赖图片的下载时间,请保证所检测图片所在的存储服务的稳定,图片建议使用oss存储或者cdn做缓存等.
  6. 接口regionId请填写cn-shanghai(你自己的服务部署在其他region,也请填写cn-shanghai)​
本文导读目录