人脸识别开放平台

一、图片上传

地址：http://face.pr.oa.com/upload_img.cgi

图片上传接口将客户端图片保存在服务器，向客户端返回URL。
如果后续人脸计算接口是以GET方式调用，则必须以该URL作为图片参数。
如果是以POST方式调用，则不需要调用此接口。

返回示例：

{
  "url":"http://face.pr.oa.com/upload_pics/fa2c46db7e501811.jpg",//图片URL
  "img_id":"fa2c46db7e501811",//图片ID
  "ret":0,//返回值，0表示上传成功
  "raw_file_type":"jpg"//原始图片类型
}

二、人脸检测和分析

地址：http://api.face.pr.qq.com/detection/detect

人脸检测接口可以在给定的图片中检测存在的人脸，并对属性进行分析。上传图片，将返回每个人脸框的位置、大小，眼睛的位置，嘴巴的位置，以及每张脸的年龄和性别。

二、人脸检测和分析

GET方式调用

调用参数如下:

参数名	参数含义
key	API Key
url	图片URL，需要urlencode，目前仅支持本站域名下的url

调用示例及返回：

http://api.face.pr.qq.com/detection/detect?url=http%3A%2F%2Fface.pr.oa.com%2Fupload_pics%2Fa9b1f0f2e0df1bcf.png&key=YOUR_KEY

{
   "url":"http://face.pr.oa.com/upload_pics/a9b1f0f2e0df1bcf.png",//原始图片URL
   "img_height":347,		//原始图像高度
   "img_width":246,		//原始图像宽度
   "ret":0,			//返回值，0表示检测成功
   "face":[			//包含脸的数组
      {
         "topleftX":69,		//人脸框左上角横坐标
         "topleftY":153,	//人脸框左上角纵坐标
         "attr":{
            "gender":"female",	//性别
            "age":24		//年龄
          },
         "eyes":{	
            "xright":163,	//右眼横坐标
            "yleft":174,	//左眼纵坐标
            "yright":178,	//右眼横坐标
            "xleft":96		//左眼横坐标
          },
         "height":132,		//人脸框高度
         "width":126,		//人脸框宽度
         "mouth":{
            "xright":154,	//右嘴角横坐标
            "yleft":243,	//左嘴角横坐标
            "yright":247,	//右嘴角纵坐标
            "xleft":100		//左嘴角横坐标
          }
      }
   ]
}

二、人脸检测和分析

POST方式调用

1.接口地址：http://api.face.pr.qq.com/detection/detect?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
若不采用加密，则POST的内容为:
request_str + “\0” + 图片内容
request_str为如下形式的字符串：
key=demo_key&pic_num=1&pic_size0=78089
其中的参数含义如下表

参数名	参数含义
key	API Key
pic_num	图片数，这里=1
pic_size0	图片的大小

若采用加密传输，则POST内容为：
AES加密( request_str + "\0" + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret

3.调用返回：

{
   "ret":0,			//返回值，0为检测成功
   "img_height":347,		//原始图像高度
   "img_width":246,		//原始图像宽度
   "face":[			//包含脸的数组
      {
         "topleftX":69,		//人脸框左上角横坐标
         "topleftY":153,	//人脸框左上角纵坐标
         "attr":{
            "gender":"female",	//性别
            "age":24		//年龄
         },
         "eyes":{
            "xright":163,	//右眼横坐标
            "yleft":174,	//左眼纵坐标
            "yright":178,	//右眼纵坐标
            "xleft":96		//左眼横坐标
         },
         "height":132,		//人脸框高度
         "width":126,		//人脸框宽度
         "mouth":{
            "xright":154,	//右嘴角横坐标
            "yleft":243,	//左嘴角纵坐标
            "yright":247,	//右嘴角纵坐标
            "xleft":100		//左嘴角横坐标
         }
      }
   ]
}

三、人脸相似度比较

地址：http://api.face.pr.qq.com/compare

接收两张图片，对两张图中的脸进行对比，返回找到的脸和相似度。相似度为0-1的小数。

三、人脸相似度比较

GET方式调用

调用参数如下:

参数名	参数含义
key	API Key
url	图片1的URL，需要urlencode，目前仅支持本站域名下的url
url2	图片2的URL，需要urlencode，目前仅支持本站域名下的url

调用示例及返回：

http://api.face.pr.qq.com/compare?url=http%3A%2F%2Fface.pr.oa.com%2Fupload_pics%2Fa9b1f0f2e0df1bcf.png&url2=http%3A%2F%2Fface.pr.oa.com%2Fupload_pics%2Fa9b1f0f2e0df1bcf.png&key=YOUR_KEY

{
   "ret":0,		//返回值，0为执行成功
   "scores":[
      [
         0.5204994082450867,
         0.549809992313385,
         0.568635880947113
      ]
   ],//二维数组，两组人脸相似度得分，若两张图片中检测到的人脸数分别为n和m，则此二维数组为n行m列
   "url":"http://face.pr.oa.com/upload_pics/3f50a772b95e3516.jpg",//第一张图片URL
   "img_width":194,	//第一张图像宽度
   "img_height":243,	//第一张图像高度
   "face":[		//第一张图片中检测到的人脸数组
      {			//第一张图中的第一张脸
         "topleftX":60,
         "topleftY":54,
         "eyes":{
            "xright":111,
            "yleft":70,
            "yright":66,
            "xleft":76
         },
         "height":68,
         "width":68,
         "mouth":{
            "xright":111,
            "yleft":108,
            "yright":106,
            "xleft":89
         }
      }
   ],
   "url2":"http://face.pr.oa.com/upload_pics/241959ab9fa8b90c.jpg",//第二张图片URL
   "img_height2":441,	//第二张图像高度
   "img_width2":632,	//第二张图像宽度
   "face2":[		//第二张图片中找到的人脸数组
      {			//第二张图中的第一张人脸
         "topleftX":99,
         "topleftY":75,
         "eyes":{
            "xright":132,
            "yleft":87,
            "yright":85,
            "xleft":109
         },
         "height":48,
         "width":46,
         "mouth":{
            "xright":131,
            "yleft":109,
            "yright":108,
            "xleft":112
         }
      },
      {			//第二张图中的第二张人脸
         "topleftX":396,
         "topleftY":166,
         "eyes":{
            "xright":433,
            "yleft":182,
            "yright":179,
            "xleft":411
         },
         "height":55,
         "width":55,
         "mouth":{
            "xright":432,
            "yleft":203,
            "yright":200,
            "xleft":414
         }
      },
      {			//第二张图中的第三张人脸
         "topleftX":276,
         "topleftY":271,
         "eyes":{
            "xright":311,
            "yleft":283,
            "yright":280,
            "xleft":289
         },
         "height":52,
         "width":50,
         "mouth":{
            "xright":308,
            "yleft":307,
            "yright":306,
            "xleft":294
         }
      }
   ]
}

三、人脸相似度比较

POST方式调用

1.接口地址：http://api.face.pr.qq.com/compare?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
若不采用加密，则POST的内容为：
request_str + “\0” + 图片内容
request_str为如下形式的字符串：
key=demo_key&pic_num=2&pic_size0=78089&pic_size1=162495
其中参数的含义如下表

参数名	参数含义
key	API Key
pic_numt	图片数，这里=2
pic_size0	第一张图片的大小
pic_size1	第二张图片的大小

若采用加密传输，则POST内容为：
AES加密( request_str + “\0” + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret

3.调用返回：

{
   "ret":0,		//返回值，0为执行成功
   "scores":[
      [
         0.5204994082450867,
         0.549809992313385,
         0.568635880947113
      ]
   ],//二维数组，两组人脸相似度得分，若两张图片中检测到的人脸数分别为n和m，则此二维数组为n行m列
   "img_width":194,	//第一张图像宽度
   "img_height":243,	//第一张图像高度
   "face":[		//第一张图片中检测到的人脸数组
      {			//第一张图中的第一张脸
         "topleftX":60,
         "topleftY":54,
         "eyes":{
            "xright":111,
            "yleft":70,
            "yright":66,
            "xleft":76
         },
         "height":68,
         "width":68,
         "mouth":{
            "xright":111,
            "yleft":108,
            "yright":106,
            "xleft":89
         }
      }
   ],
   "img_height2":441,	//第二张图像高度
   "img_width2":632,	//第二张图像宽度
   "face2":[		//第二张图片中找到的人脸数组
      {			//第二张图中的第一张人脸
         "topleftX":99,
         "topleftY":75,
         "eyes":{
            "xright":132,
            "yleft":87,
            "yright":85,
            "xleft":109
         },
         "height":48,
         "width":46,
         "mouth":{
            "xright":131,
            "yleft":109,
            "yright":108,
            "xleft":112
         }
      },
      {			//第二张图中的第二张人脸
         "topleftX":396,
         "topleftY":166,
         "eyes":{
            "xright":433,
            "yleft":182,
            "yright":179,
            "xleft":411
         },
         "height":55,
         "width":55,
         "mouth":{
            "xright":432,
            "yleft":203,
            "yright":200,
            "xleft":414
         }
      },
      {			//第二张图中的第三张人脸
         "topleftX":276,
         "topleftY":271,
         "eyes":{
            "xright":311,
            "yleft":283,
            "yright":280,
            "xleft":289
         },
         "height":52,
         "width":50,
         "mouth":{
            "xright":308,
            "yleft":307,
            "yright":306,
            "xleft":294
         }
      }
   ]
}

四、明星脸搜索

地址：http://api.face.pr.qq.com/search?type=star_face

接收1张图片，找出其中所有的脸，并返回每一张脸最相似的明星脸。

四、明星脸搜索

GET方式调用

调用参数如下:

参数名	参数含义
key	API Key
url	图片的URL，需要urlencode，目前仅支持本站域名下的url
type	type=star_face表示搜索明星脸l

调用示例及返回：

http://api.face.pr.qq.com/search?type=star_face&url=http%3A%2F%2Fface.pr.oa.com%2Fupload_pics%2Fa9b1f0f2e0df1bcf.png&key=YOUR_KEY

{
   "ret":0,			//返回值，0为搜索成功
   "url":"http://face.pr.oa.com/upload_pics/e246ba294bd6844f.jpg",//原始图像URL
   "img_height":500,		//原始图像高度
   "img_width":333,		//原始图像宽度
   "face":[			//图片中找到的脸的数组
      {
         "topleftX":93,		//人脸框左上角横坐标
         "topleftY":63,		//人脸框左上角纵坐标
		 "height":138, 	//人脸框高度
         "width":138, 		//人脸框宽度
         "eyes":{
            "xright":191,
            "yleft":98,
            "yright":99,
            "xleft":127
         },
         "mouth":{
            "xright":187,
            "yleft":162,
            "yright":162,
            "xleft":132
         },
         "stars":[		//与该人脸最相似的明星脸数组，按相似度从大到小排列
            { 			//第一个明星
               "score":60.339717864990234,//相似度0-100.0
               "name":"朱军",	//明星名字
               "nLabel":1820	//明星序号
            },
            {			//第二个明星
               "score":57.09498596191406,
               "name":"曾江",
               "nLabel":1818
            },
            {
               "score":56.60051727294922,
               "name":"石康",
               "nLabel":2064
            },
            {
               "score":56.45879364013672,
               "name":"黄渤",
               "nLabel":2424
            },
            {
               "score":55.654144287109375,
               "name":"马云",
               "nLabel":2362
            }
         ]
      }
   ]
}

四、明星脸搜索

POST方式调用

1.接口地址：http://api.face.pr.qq.com/search?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
若不采用加密，则POST的内容为:
request_str + “\0” + 图片内容
request_str为如下形式的字符串：
key=demo_key&type=star_face&pic_num=1&pic_size0=78089
其中的参数含义如下表

参数名	参数含义
key	API Key
type	搜索种类，搜索明星脸为star_face
pic_num	图片数，这里=1
pic_size0	图片的大小

若采用加密传输，则POST内容为：
AES加密( request_str + "\0" + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret

3.调用返回：

{
   "ret":0,			//返回值，0为搜索成功
   "img_height":500,		//原始图像高度
   "img_width":333,		//原始图像宽度
   "face":[			//图片中找到的脸的数组
      {
         "topleftX":93,		//人脸框左上角横坐标
         "topleftY":63,		//人脸框左上角纵坐标
		 "height":138, 	//人脸框高度
         "width":138, 		//人脸框宽度
         "eyes":{
            "xright":191,
            "yleft":98,
            "yright":99,
            "xleft":127
         },
         "mouth":{
            "xright":187,
            "yleft":162,
            "yright":162,
            "xleft":132
         },
         "stars":[		//与该人脸最相似的明星脸数组，按相似度从大到小排列
            { 			//第一个明星
               "score":60.339717864990234,//相似度0-100.0
               "name":"朱军",	//明星名字
               "nLabel":1820	//明星序号
            },
            {			//第二个明星
               "score":57.09498596191406,
               "name":"曾江",
               "nLabel":1818
            },
            {
               "score":56.60051727294922,
               "name":"石康",
               "nLabel":2064
            },
            {
               "score":56.45879364013672,
               "name":"黄渤",
               "nLabel":2424
            },
            {
               "score":55.654144287109375,
               "name":"马云",
               "nLabel":2362
            }
         ]
      }
   ]
}

五、人脸注册

POST方式调用

人脸识别的第一步是人脸注册，提交一张图片，并告诉系统图中人的身份(group和tag)。
系统会在图片中找到最大的一张人脸，提取特征，并与用户提交的身份绑定，返回成功或失败。
此接口只支持加密方式的POST调用。

1.接口地址：http://api.face.pr.qq.com/recognize?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
采用加密传输，POST的内容为:
AES加密( request_str + “\0” + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret
request_str为如下形式的字符串：
key=demo_key&cmd=1&tag=john&group=0&pic_num=1&pic_size0=78089
其中的参数含义如下表

参数名	参数含义
key	API Key
cmd	人脸识别命令字，人脸注册请求cmd=1
tag	图中人的身份标签，由客户端决定
group	分组号，默认为0，客户端决定，用于划定注册和识别范围

3.调用返回：

{
   "ret":0,			//返回值，0为注册成功
   "img_height":347,		//原始图像高度
   "img_width":246,		//原始图像宽度
   "face":[			//包含脸的数组这里只返回图片中最大的一张脸
      {
         "topleftX":69,
         "topleftY":153,
		 "height":132,
         "width":126,
         "attr":{
            "gender":"female",
            "age":24
         },
         "eyes":{
            "xright":163,
            "yleft":174,
            "yright":178,
            "xleft":96
         },
         "mouth":{
            "xright":154,
            "yleft":243,
            "yright":247,
            "xleft":100
         }
      }
   ]
}

六、人脸删除

POST方式调用

删除指定group中指定的tag。
此接口只支持加密方式的POST调用。

1.接口地址：http://api.face.pr.qq.com/recognize?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
采用加密传输，POST的内容为:
AES加密( request_str + “\0” + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret
request_str为如下形式的字符串：
key=demo_key&cmd=2&group=0&tag=john
其中的参数含义如下表

参数名	参数含义
key	API Key
cmd	人脸识别命令字，人脸删除请求cmd=2
group	分组号
tag	要删除的人脸tag

3.调用返回：

{
   "ret":0,			//返回值，0为删除成功
}

七、人脸识别

POST方式调用

提交一张图片，系统以图片中最大的脸在指定的group中找到与该脸相似度最高的一组tag。
此接口只支持加密方式的POST调用。

1.接口地址：http://api.face.pr.qq.com/recognize?key=YOUR_KEY&encrypt=1
其中的参数含义如下表

参数名	参数含义
key	API Key
encrypt	是否采用加密：1为采用；0为不采用

2.POST内容：
采用加密传输，POST的内容为:
AES加密( request_str + “\0” + 图片内容)
POST内容采用AES算法加密，加密密钥为注册时获得的API secret
request_str为如下形式的字符串：
key=demo_key&cmd=4&group=0&pic_num=1&pic_size0=78089
其中的参数含义如下表

参数名	参数含义
key	API Key
cmd	人脸识别命令字，人脸识别请求cmd=4
group	分组号，默认为0，客户端决定，用于划定注册和识别范围
pic_num	图片数，这里为1
pic_size0	图片大小

3.调用返回：

{
   "ret":0,		//返回值，0为识别成功
   "img_height":347,	//原始图像高度
   "img_width":246,	//原始图像宽度
   "face":[		//包含脸的数组这里只返回图片中最大的一张脸
      {
         "topleftX":69,
         "topleftY":153,
         "attr":{
            "gender":"female",
            "age":24
         },
         "eyes":{
            "xright":163,
            "yleft":174,
            "yright":178,
            "xleft":96
         },
         "height":132,
         "width":126,
         "mouth":{
            "xright":154,
            "yleft":243,
            "yright":247,
            "xleft":100
         }
      }
   ],
   "tags":[//与该人脸最相似的人的身份数组，按相似度从大到小排列
      {			//第一个人
         "score":60.339717864990234,
         "tag":"朱军"
      },
      { 		//第二个人
         "score":57.09498596191406,
         "tag":"曾江"
      }
   ]
}

文档

一、图片上传

二、人脸检测和分析

二、人脸检测和分析

GET方式调用

二、人脸检测和分析

POST方式调用

三、人脸相似度比较

三、人脸相似度比较

GET方式调用

三、人脸相似度比较

POST方式调用

四、明星脸搜索

四、明星脸搜索

GET方式调用

四、明星脸搜索

POST方式调用

五、人脸注册

POST方式调用

六、人脸删除

POST方式调用

七、人脸识别

POST方式调用