多脸检索

最近更新时间:2019-04-25 18:41:14

注意:

  • 人脸识别全面升级接口,算法更强、性能更优,欢迎立即体验 人脸识别
  • 人脸识别新老版本的接口不兼容,控制台的数据统计不互通,但计费模式相同,且共享计费阶梯。
  • 人员库管理(原个体信息管理)新老版本的人脸特征数据不互通,未来老版本将不再升级,建议您尽快迁移至新版本。
  • 人脸识别1.0版本将于2019年6月20日后停止服务,请您在此之前将账号下的接口更换到 2.0版本

接口描述

接口请求域名:https://recognition.image.myqcloud.com/face/multidentify

本接口(multidentify)用于对一张包含多个待识别的人脸的图片,在一个 group 或多个 groups 中识别出最相似的 person 作为其身份返回,返回的 Top5 中按照相似度从大到小排列。

说明:

  • 本接口支持 HTTPS 协议,如果您现在使用的是 HTTP 协议,为了保障您的数据安全,请切换至 HTTPS。

基本概念

概念 解释
appid 接入项目的唯一标识,可在 账号信息云 API 密钥 中查看。
group_id 个体(person)以组(group)的形式存储,一个组可以包含多个个体,一个个体也可以存在于多个组。group_id 即用来标识 group 。组(group)没有专门的创建接口,创建个体(person)时,指定 group_id 则会自动创建。
person_id 人脸以个体(person)的形式存储,一个个体下可以存储多张人脸,即用来标识 person。
face_id 标识每张人脸的 ID。

说明:

如果开发者使用的是 V1 版本,则 appid 为其当时生成的 APPID。

group 信息管理接口如下:

接口 描述
创建个体 创建一个 person ,并将 person 放置到 group_ids 指定的组当中,不存在的 group_id 会自动创建。
删除个体 删除一个 person 。
增加人脸 将一组 face 加入到一个 person 中。注意,一个 face 只能被加入到一个 Person 中。 一个 person 最多允许包含 20 个 face ;加入几乎相同的人脸会返回错误。
删除人脸 删除一个 person 下的 face ,包括特征,属性和 face_id 。
设置信息 设置 person 的 name 。
获取信息 获取一个 person 的信息,包括 name、ID、tag、相关的 face、以及 groups 等信息。
获取组列表 获取一个 appid 下所有 group 列表。
获取人列表 获取一个组 group 中所有 person 列表。
获取人脸列表 获取一个组 person 中所有 face 列表。
获取人脸信息 获取一个 face 的相关特征信息。

注意:

  • 一个 appid 下建立的 group_id 数量限制为 5000 个。
  • 一个 group_id 下建立的 person_id 数量限制为 20000 个。
  • 一个 person_id 下建立的人脸数量限制为 20 个。
  • 每个请求的包体大小限制为 1.5MB , 不支持 .gif 类型的动图。

请求包 header

参数名 必选 描述
host recognition.image.myqcloud.com 腾讯云人脸识别服务器域名
content-length 包体总长度 整个请求包体内容的总长度,单位:字节(Byte)
content-type application/json 或 multipart/form-data 据不同接口选择:
1. 使用 application/json 格式,参数为 url,其值为图片的 url ;
2. 使用 multipart/form-data 格式,参数为 image,其值为图片的二进制内容。
authorization 鉴权签名 多次有效签名,用于鉴权,生成方式见 鉴权签名方法

注意:
选择 multipart/form-data,请使用 HTTP 框架/库推荐的方式设置请求的 content-type,不推荐直接调用 setHeader 等方法设置,否则可能导致 boundary 缺失引起请求失败。

输入参数

使用 application/json 格式,参数选择 url ;使用multipart/form-data 格式,参数选择 image。

参数名 必选 类型 参数说明
appid String 接入项目的唯一标识,可在 账号信息云 API 密钥 中查看
group_id String 候选人组 ID、group_id 和 group_ids 只提供一个即可
group_ids Array(String) 候选人组 ids
image Binary 图片内容
url String 图片的 url , image 和 url 只提供一个即可,如果都提供,只使用 url
session_id String session_id

输出参数

字段 类型 说明
data.session_id String 相应请求的 session 标识符,可用于结果查询
data.results Array (multiIdentifyItem) 识别结果
code Int 返回状态码
message String 返回错误消息

multiIdentifyItem 说明:

字段 类型 说明
candidates identifyItem 候选者 识别结果
face_rect facerectItem 候选者 人脸框位置

identifyitem 说明:

字段 类型 说明
person_id String 候选者 person_id
face_id String 候选者 face_id
confidence Float 候选者的置信度
tag String 人脸备注信息

facerectitem 说明:

字段 类型 说明
x Int32 人脸位置左上角横坐标
y Int32 人脸位置左上角纵坐标
width Int32 人脸宽度
height Int32 人脸高度

注意:
如果图片中包含超过 5 张人脸,在返回的 FaceItem 中,只返回 5 张人脸完整信息,其他人脸只返回位置信息(face_id,x,y,width,height),属性信息不返回。

示例

输入示例

使用 url 和 group_id

POST /face/multidentify HTTP/1.1
Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi==
Host: recognition.image.myqcloud.com
Content-Length: 123
Content-Type: application/json

{
  "appid":"123456",
  "group_id":"tencent",
  "url":"http://test-123456.image.myqcloud.com/test.jpg"
}

使用 url 和 group_ids

POST /face/multidentify HTTP/1.1
Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi==
Host: recognition.image.myqcloud.com
Content-Length: 123
Content-Type: application/json

{
  "appid":"123456",
  "group_ids":["tencent","qq"]
  "url":"http://test-123456.image.myqcloud.com/test.jpg"
}

使用 image 和 group_id

POST /face/multidentify HTTP/1.1
Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi==
Host: recognition.image.myqcloud.com
Content-Length: 460
Content-Type: multipart/form-data;boundary=--------------acebdf13572468

----------------acebdf13572468
Content-Disposition: form-data; name="appid";

123456
----------------acebdf13572468
Content-Disposition: form-data; name="group_id";

tencent
----------------acebdf13572468
Content-Disposition: form-data; name="image"; filename="test.jpg"
Content-Type: image/jpeg

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
----------------acebdf13572468--

使用 image 和 group_ids

POST /face/multidentify HTTP/1.1
Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi==
Host: recognition.image.myqcloud.com
Content-Length: 460
Content-Type: multipart/form-data;boundary=--------------acebdf13572468

----------------acebdf13572468
Content-Disposition: form-data; name="appid";

123456
----------------acebdf13572468
Content-Disposition: form-data; name="group_ids[0]";

tencent
----------------acebdf13572468
Content-Disposition: form-data; name="group_ids[1]";

qq
----------------acebdf13572468
Content-Disposition: form-data; name="image"; filename="test.jpg"
Content-Type: image/jpeg

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
----------------acebdf13572468--

输出示例

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 409
Content-Type: application/json

{
  "data":{
    "session_id": "111",
    "results": [{
      "candidates": [{
        "person_id": "person1",
        "face_id": "10001",
        "confidence": 64,
        "tag": ""
      }, {
        "person_id": "person2",
        "face_id": "100002",
        "confidence": 12,
        "tag": ""
      }],
      "face_rect": {
        "x": 60,
        "y": 80,
        "width": 50,
        "height": 60
      }
    }]
  },
  "code":0,
  "message":"OK"
}

错误码

错误码 含义
3 错误的请求;其中 message:account abnormal,errorno is:2 为账号欠费停服
4 签名为空
5 签名串错误
6 签名中的 APPID /存储桶与操作目标不匹配
9 签名过期
10 APPID 不存在
11 SecretId 不存在
12 APPID 和 SecretId 不匹配
13 重放攻击
14 签名校验失败
15 操作太频繁,触发频控
16 存储桶不存在
21 无效参数
23 请求包体过大
24 本接口即将下线,请使用 新版人脸识别
107 鉴权服务不可用
108 鉴权服务不可用
213 内部错误
-1101 人脸检测失败
-1102 图片解码失败
-1103 特征处理失败
-1104 提取轮廓错误
-1105 提取性别错误
-1106 提取表情错误
-1107 提取年龄错误
-1108 提取姿态错误
-1109 提取眼镜错误
-1200 特征存储错误
-1300 图片为空
-1301 参数为空
-1302 个体已存在
-1303 个体不存在
-1304 参数过长
-1305 人脸不存在
-1306 组不存在
-1307 组列表不存在
-1308 url 图片下载失败
-1309 人脸个数超过限制
-1310 个体个数超过限制
-1311 组个数超过限制
-1312 对个体添加了几乎相同的人脸
-1313 参数不合法(特殊字符比如空格、斜线、tab、换行符)
-1400 非法的图片格式
-1403 图片下载失败

更多其他 API 错误码请查看 错误码说明