接入文档
FaceID基础版
APP接入
人脸验证API(V2版本)
Detect API
Detect API

2017-02-22,V1.0.1

# API和能力升级

新增对image参数图片的旋转检测能力,详情见新增的multi_oriented_detection参数描述。

# 简介

此接口检测一张照片中的人脸,便于后续的人脸比对。
因为FaceID Verify接口假设待比对的照片必须是有且只有一张人脸的正面大头照,对于不使用FaceID MegLive活体检查模块获得大头照的用户,Detect接口提供了从一张图片里直接获得大头照的方式。

# 调用URL

https://api.faceid.com/faceid/v1/detect

注意:在生产环境中,请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路,存在安全风险,请勿在生产环境中使用。在生产环境中使用HTTP方式的,将无法得到服务可靠性保障。

# 调用方法

POST  注意:用form-data格式请求

# 参数

必选/可选 参数名 类型 参数说明
必选 api_key String 用于验证客户身份的API Key; 对于每一个客户此字段不会变更,相当于用户名
必选 api_secret String 用于验证客户身份的API Secret; 对于每一个客户可以申请变更此字段,相当于密码
必选 image File 通过非MegLive的途径获得的真人人脸照片
可选 multi_oriented_detection String 对image参数启用图片旋转检测功能。当image参数中传入的图片未检测到人脸时,是否对图片尝试旋转90度、180度、270度后再检测人脸。本参数取值只能是 "1"或 "0" (缺省值为"0"):
  • "1":启用旋转检测(启用旋转检测后,会增加API的调用时间)
  • "0":不启用旋转检测
  • 其他值:返回错误码400(BAD_ARGUMENTS)
  • 注意:设置此参数为1可能会轻微增加误检人脸的概率,如果您明确您的业务场景里不存在非正向的人脸图片、或概率极低,建议勿设置此参数
    可选 separate_face String 对image参数启用图片切分功能,如果包含多人脸,将多张脸切分对应照片:
  • "1":启用(启用后,会返回多张脸对应的照片)
  • "0":不启用(默认)
  • 其他值:返回错误码400(BAD_ARGUMENTS)
  • # 返回值

    API返回的为一个JSON字符串。

    字段 类型 说明
    request_id String 用于区分每一次请求的唯一字符串
    time_used Float 整个请求所花费的时间,单位为毫秒
    faces Array 在照片中所有找到的人脸,都以Json的形式返回,并组成一个Array
  • 当启用图片切分功能(separate_face=1),返回image:base64人脸图片(多个人脸,按人脸大小降序)
  • quality Float 每一个人脸都会有一个质量判断的分数
    quality_threshold Float 表示人脸质量基本合格的一个阈值,超过该阈值的人脸适合用于人脸比对
    rect Json 图片中人脸框的位置,会用一个Json表示
    left Float 人脸框的左上角(以图片宽度的比例给出)的x坐标
    top Float 人脸框的左上角(以图片高度的比例给出)的y坐标
    width Float 人脸框的宽度(以图片宽度的比例给出)
    height Float 人脸框的高度(以图片宽度的比例给出)
    token String 用于标示每一个人脸的唯一字符串,可以用于verify上的face_token
    orientation Int 本字段仅在参数 multi_oriented_detection为“1”时才返回,表示人脸框的朝向,目前仅取0、90、180或270,单位为度,按顺时针方向。以人脸来说,0度表示通常意义上的正向、90度为头顶朝右下巴朝左、180度表示上下颠掉、270度表示头顶朝左下巴朝右。按此角度逆时针旋转图片即可获得正向的人像照

    # 返回值示例

    正确请求返回示例

    {
       "time_used":320,
       "request_id":"1457432550,b70ab3a8-ee37-4f90-a2bd-007e23a970e2",
       "faces":[
          {
             "quality":38.22176746384912,
             "quality_threshold":30.1,
             "rect":{
                "left":0.18,
                "top":0.18,
                "width":0.5966667,
                "height":0.5966667
             },
             "orientation":90,
             "token":"Rihc25px-qjfYWBq5MRdy2HaE7FWKSaEj-J2qLEyMLY="
          }
       ]
    }
    

    请求失败返回示例

    {
       "time_used":0,
       "request_id":"1457432550,b70ab3a8-ee37-4f90-a2bd-007e23a970e2",
       "error":"IMAGE_ERROR_UNSUPPORTED_FORMAT"
    } 
    
    HTTP状态代码 错误信息 说明
    400 MISSING_ARGUMENTS:key 缺少某个必要参数
    400 IMAGE_ERROR_UNSUPPORTED_FORMAT 上传的图像无法正确解析,其可能不是一个图像文件
    400 INVALID_IMAGE_SIZE:<param> 上传的图像像素尺寸的长或宽超过4096像素,此处param为image
    400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.)
    403 AUTHORIZATION_ERROR 客户身份信息验证不通过
    403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
    413 Request Entity Too Large 客户发送的请求大小超过了2MB限制。该错误的返回格式为纯文本,不是json格式
    404 API_NOT_FOUND 所调用的API不存在
    500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果一直出现此类错误,请及时联系客服

    # 调用示例

    curl "https://api.faceid.com/faceid/v1/detect" –F api_key=<api_key> -F api_secret=<api_secret> –F image=@customer.jpg

    该文档未解决您的疑问?查看常见问题