人脸识别
有奖征文：腾讯云大模型知识引擎xDeepSeek > HOT
文档中心>人脸识别>API 文档>人脸识别 API 2017>人脸检索

人脸检索

最近更新时间：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
据不同接口选择：<br/>1. 使用 application/json 格式，参数为 url，其值为图片的 url。<br/>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 错误码请查看 错误码说明 。
中国站
文档活动
message-icon联系我们
目录