注意：
接口描述
接口请求域名：https://recognition.image.myqcloud.com/face/identify
本接口（identify）用于对一张待识别的人脸图片，在一个或多个 group 中识别出最相似的 Top5 person 作为其身份返回，返回的 Top5中按照相似度从大到小排列。
注意：
- 本接口支持 HTTPS 协议，如果您现在使用的是 HTTP 协议，为了保障您的数据安全，请切换至 HTTPS。
基本概念
| 概念 | 解释 |
|---|---|
| appid | 接入项目的唯一标识，可在 账号信息 或 云 API 密钥 中查看。 |
| group_id | 个体( person )以组（ group ）的形式存储，一个组可以包含多个个体，一个个体也可以存在于多个组。group_id 即用来标识 group 。组( group )没有专门的创建接口，创建个体( person )时，指定 group_id 则会自动创建。 |
| person_id | 人脸以个体（ person ）的形式存储，一个个体下可以存储多张人脸。person_id 即用来标识 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 和 image， 此时 image 须为经 base64编码后的 String，参数类型为 String。
使用 multipart/form-data 格式时， 参数可选择 url 和 image， 此时 image 须为 Binary 格式， 参数类型为 Binary。
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| appid | 是 | String | 接入项目的唯一标识，可在 账号信息 或 云 API 密钥 中查看。 |
| group_id | 否 | String | 候选人组 ID，与 group_ids 二选一即可。 |
| group_ids | 否 | Array(String) | 候选人组 ID 列表，与 group_id 二选一即可。 |
| image | 否 | Binary 或 String | 图片二进制内容或经 base64转码后的字符串。 |
| url | 否 | String | image 和 url 只需提供一个；如果都提供，只使用 url。 |
输出参数
| 字段 | 类型 | 说明 |
|---|---|---|
| data.session_id | String | 相应请求的 session 标识符，可用于结果查询。 |
| data.candidates | Array(IdentifyItem) | 识别出的 Top5候选人。 |
| code | Int | 返回状态码。 |
| message | String | 返回错误消息。 |
IdentifyItem 说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| person_id | String | 候选者 person_id |
| face_id | String | 候选者 face_id |
| confidence | Float | 候选者的置信度 |
| tag | String | 人脸备注信息 |
示例
输入示例
使用 url
POST /face/identify 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"
}POST /face/identify 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
POST /face/identify 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--POST /face/identify 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":"session_id",
"candidates":[
{
"person_id":"person3",
"face_id":"1031567119985213439",
"confidence":54.90695571899414,
"tag":"new tag"
},
{
"person_id":"person1",
"face_id":"1031587105968553983",
"confidence":54.86775207519531,
"tag":"new tag"
}
]
},
"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 错误码请查看 错误码说明 。
