注意:
接口描述
接口请求域名: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 错误码请查看 错误码说明。