人脸检测

注意：

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

接口描述

接口请求域名：https://recognition.image.myqcloud.com/face/detect
本接口（detect）用于检测给定图片中的所有人脸( Face )的位置和相应的面部属性，位置包括(x，y，w，h)，面部属性包括性别( gender )、年龄( age )、表情( expression )、魅力( beauty )、眼镜( glass )和姿态 (pitch，roll，yaw )。

注意：

• 本接口支持 HTTPS 协议，如果您现在使用的是 HTTP 协议，为了保障您的数据安全，请切换至 HTTPS。

请求头 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 密钥 中查看。
mode	否	Int	检测模式，0：所有人脸，1：最大的人脸。
image	否	Binary	图片内容。
url	否	String	图片的 url、image提供一个即可；如果都提供，只使用 url

输出参数

字段	类型	说明
data.session_id	String	相应请求的 session 标识符，可用于结果查询。
data.image_width	Int	请求图片的宽度。
data.image_height	Int	请求图片的高度。
data.face	Array(faceItem)	检测出的人脸信息列表。
code	Int	返回状态码。
message	String	返回错误消息。

FaceItem 说明：

字段	类型	说明
face_id	String	人脸标识
x	Int	人脸框左上角 x
y	Int	人脸框左上角 y
width	Float	人脸框宽度
height	Float	人脸框高度
gender	Int	性别 [0(female)~100(male)]
age	Int	年龄 [0~100]
expression	Int	微笑[0(normal)~50(smile)~100(laugh)]
glass	Bool	是否有眼镜 [true,false]
pitch	Int	上下偏移[-30,30]
yaw	Int	左右偏移[-30,30]
roll	Int	平面旋转[-180,180]
Beauty	Int	魅力[0~100]

注意：

如果图片中包含超过5张人脸，在返回的 FaceItem 中，只返回5张人脸完整信息，其他人脸只返回位置信息(face_id，x，y，width，height)，属性信息不返回。

示例

输入示例

使用 url 的请求包

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

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

使用 image 的请求包

POST /face/detect 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="mode";

1
----------------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: 313
Content-Type: application/json

{
  "data":{
    "session_id": "",
    "image_height": 200,
    "image_width": 200,
    "face": [{
      "face_id": "1005338790489817087",
      "x": 44,
      "y": 33,
      "height": 64.0,
      "width": 64.0,
      "pitch": 5,
      "roll": 0,
      "yaw": 6,
      "age": 37,
      "gender": 99,
      "glass": true,
      "expression": 6
      "beauty": 80
}]
  },
  "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 错误码请查看 错误码说明 。