人脸检索

最近更新时间:2020-06-29 15:08:11

注意:

  • 人脸识别全面升级接口,算法更强、性能更优,欢迎立即体验 人脸识别
  • 人脸识别新老版本的接口不兼容,控制台的数据统计不互通,但计费模式相同,且共享计费阶梯。
  • 人员库管理(原个体信息管理)新老版本的人脸特征数据不互通,老版本已停止升级,建议您尽快迁移至新版本。
  • 人脸识别1.0版本接口已从2019年6月21日起停止维护,如果您使用的仍是当前的旧接口,请尽快升级成 2.0版本接口

接口描述

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