有奖捉虫:云通信与企业服务文档专题,速来> HOT
注意:

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

接口描述

接口请求域名:https://recognition.image.myqcloud.com/face/verify
本接口(verify)用于给定一个图片和一个 Person 时,检查是否是同一个人。

注意:

  • 本接口支持 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

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

参数名 必选 类型 参数说明
appid String 接入项目的唯一标识,可在 账号信息云 API 密钥 中查看。
person_id String 待验证的 person。
image Binary 图片内容。
url String 图片的 url、image 和 url 只提供一个就可以了,如果都提供,只使用 url。

输出参数

字段 类型 说明
data.session_id String 相应请求的 session 标识符,可用于结果查询
data.confidence Float 两个人的相似度
data.ismatch Bool 两个输入是否为同一人的判断
code Int 返回状态码
message String 返回错误消息

示例

输入示例

使用 url

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

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

使用 image

POST /face/verify 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="person_id";

Person1
----------------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",
"confidence":90.0,
"ismatch":true
  },
  "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 错误码请查看 错误码说明