人脸识别

最近更新时间:2020-07-17 16:59:55

人脸识别API文档

目录

调用方式

请求结构

服务地址 AI开放服务API的服务接入地址为:http://kcr.api.ksyun.com

通信协议

支持通过HTTP或HTTPS协议进行请求通信。为保证您的服务安全性,请使用HTTPS协议进行通信。

请求方式

支持GET方法发送请求,注意参数需要进行urlencode。

公共参数

公共请求header

参数名 必选 类型 说明
Authorization string 必要的请求验证信息
X-Amz-Date string 当前请求的时间戳,例如:20171129T114852Z
Host string kcr.api.ksyun.com

签名参数

Region:金山云机房信息,目前仅支持cn-beijing-6

Service:固定为kcr

返回结果

接口统一返回json格式数据,满足以下格式:

{
    "header":{
      "err_no":200,
      "err_msg":"success"
    },
    "cost":0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1234567890123,
    "body":{}
}

调用成功,err_no返回200,msg为success,否则返回对应错误码及错误信息。

cost为服务端耗时,单位秒。

每此请求会返回唯一的请求表示request_id,调用失败时提供request_id给金山云客服,方便定位问题。

request_time为每次请求时的服务器时间。

签名机制

详见金山云签名机制文档

人脸检测与分析接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=DetectFace string 固定此值
Version=2019-12-13 string API版本号,固定此值

POST请求示例

{
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)
need_attributes string 是否检测人体属性,默认不检测

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "2216eaa9-52d2-4e0f-a690-e79b10a2c2fe",
    "cost": 0.495,
    "face_num": 2,
    "face_info": [
        {
            "attributes": {
                "headwear": {
                    "rate": 0.323924720287323,
                    "name": "未戴帽子"
                },
                "gender": {
                    "rate": 0.8240132331848145,
                    "name": "女性"
                },
                "age": {
                    "rate": 0.9495382308959961,
                    "name": "青年"
                },
                "glasses": {
                    "rate": 0.9292197823524475,
                    "name": "普通眼镜"
                },
                "mask": {
                    "rate": 0.7128473520278931,
                    "name": "戴口罩"
                },
                "race": {
                    "rate": 0.4870010614395142,
                    "name": "维族"
                }
            },
            "location": {
                "top_left_x": 0.16029005560994847,
                "top_left_y": 0.2177239403843063,
                "bottom_right_y": 0.3159262808263047,
                "bottom_right_x": 0.20467229934001807,
                "rate": 0.9999997615814209
            }
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
face_num int 图像中人脸个数
face_info.location object 图像中人脸位置信息
face_info.location.top_left_x double 人脸左上坐标的x值
face_info.location.top_left_y double 人脸左上坐标的y值
face_info.location.bottom_right_x double 人脸右下坐标的x值
face_info.location.bottom_right_y double 人脸右下坐标的y值
face_info.location.rate double 人脸置信度
face_info.attributes object 人脸属性信息
face_info.attributes.gender object 人脸性别
face_info.attributes.gender.name string 男性、女性
face_info.attributes.gender.rate double 置信度
face_info.attributes.age object 人脸年龄
face_info.attributes.age.name string 儿童、少年、青年、中年、老年
face_info.attributes.age.rate double 置信度
face_info.attributes.headwear object 戴帽子
face_info.attributes.headwear.name string 未戴帽子、戴头盔、戴帽子
face_info.attributes.headwear.rate double 置信度
face_info.attributes.glasses object 人脸戴眼镜
face_info.attributes.glasses.name string 普通眼镜、太阳镜、未戴眼镜
face_info.attributes.glasses.rate double 置信度
face_info.attributes.mask object 人脸戴口罩
face_info.attributes.mask.name string 戴口罩、无口罩
face_info.attributes.respirator.rate double 置信度
face_info.attributes.race object 民族
face_info.attributes.race.name string 维族、非维族
face_info.attributes.race.rate double 置信度

注:为保证图片缩放后坐标点不变,此处返回坐标值均为相对图片长宽的百分比。

人脸比对接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=CalculateFaceSimilarity string 固定此值
Version=2019-12-13 string API版本号,固定此值

POST请求示例

{
    "image1_url":"https://datasets.ks3-cn-beijing.ksyun.com/liandanlu/401ffac2d0b9706f7222e54833a1e7e5.jpg",
    "image2_url":"https://datasets.ks3-cn-beijing.ksyun.com/liandanlu/401ffac2d0b9706f7222e54833a1e7e5.jpg"
}

POST参数说明

参数 必选 类型 说明
image1_url string 对比图片1的url(image1_url和image1_data二选一)
image1_data string 对比图片1的内容的BASE64编码 (image1_url和image1_data二选一)
image2_url string 对比图片2的url(image2_url和image2_data二选一)
image2_data string 对比图片2的内容的BASE64编码 (image2_url和image2_data二选一)

注:如果使用图像base64传输,请注意整体请求不能超过1MB。

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "090e40f5-f90c-4921-b058-30f1a7e83c3d",
    "rate": 0.82,
    "cost": 0.627,
    "img1_face_info": {
        "face_num": 1,
        "location": [
            {
                "top_left_x": 0.3674023490748368,
                "top_left_y": 0.17655514139411357,
                "bottom_right_y": 0.7315950006291683,
                "bottom_right_x": 0.6000457712216303,
                "rate": 0.9999995231628418
            }
        ]
    },
    "img2_face_info": {
        "face_num": 1,
        "location": [
            {
                "top_left_x": 0.3674023490748368,
                "top_left_y": 0.17655514139411357,
                "bottom_right_y": 0.7315950006291683,
                "bottom_right_x": 0.6000457712216303,
                "rate": 0.9999995231628418
            }
        ]
    }
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
rate double 人脸相似度(若图像中含有多张人脸,以宽度最大的人脸做为对比人脸)
img1_face_info object 对比图像1的人脸识别详细信息
img2_face_info object 对比图像2的人脸识别详细信息
face_num int 图像中人脸个数
location object 图像中人脸位置信息
location.top_left_x double 人脸左上坐标的x值
location.top_left_y double 人脸左上坐标的y值
location.bottom_right_x double 人脸右下坐标的x值
location.bottom_right_y double 人脸右下坐标的y值
location.rate double 人脸置信度

注:为保证图片缩放后坐标点不变,此处返回坐标值均为相对图片长宽的百分比。

活体检测接口

注意事项

  • 请求体格式化:Content-Type为application/json,通过json格式化请求体
  • Base64编码:图片的base64编码是指将图片数据编码成一串字符串,使用该字符串代替图像地址,首先得到图片的二进制,然后用Base64格式编码即可。注意:图片的base64编码是不包含图片头的,比如data:image/jpg;base64
  • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

HTTP请求方式

post

输入

GET参数部分

参数名 必选 类型 说明
Action=FaceVerify string 固定此值
Version=2020-07-16 string API版本号,固定此值

Body参数

{"images":[
      {"image_url":"http://www.baidu.com/image/QKA666.jpg",
        "face_field":"quality",
        "option":"COMMON"}
      ]
 }

 或

 {"images":[
      {"image_data":"9jjiuuyu86sadw00...",
        "face_field":"quality",
        "option":"COMMON"}
      ]
 }

Body参数说明

参数 必选 类型 说明
image_url 可选 string 图片URL(image_url和image_data必须二选一,图片大小不超过2M)
image_data 可选 string Base64编码后的图片,需urlencode,编码后的图片大小不超过2M
face_field 可选 string 当前只支持固定值quality,可不指定该参数,接口将默认采用quality
option 可选 string 场景信息,程序会视不同的场景选用相对应的模型,当前支持的场景有COMMON(通用场景),GATE(闸机场景),默认使用COMMON

输出

接口返回示例:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "cost": 3.29,
    "result": {
        "thresholds": {
            "frr_1e-4": 0.05,
            "frr_1e-3": 0.3,
            "frr_1e-2": 0.9
        },
        "face_liveness": 1.0,
        "face_list": [
               {
                "location": {
                    "left": 222.23,
                    "top": 414.4,
                    "width": 320.0,
                    "height": 353.0,
                    "rotation": 1
                },
                "angle": {
                    "yam": 0.0,
                    "pitch": -0.1,
                    "roll": -0.44
                },
                "quality": {
                    "blur": 0.0,
                    "illumination": 88.0,
                    "completeness": 1
                },
                "face_token": "8d362ef6b11de723358893ebb770061f",
                "face_probability": 1.0
            }
        ]
    },
    "request_id": "\"123\""
}

接口输出字段说明

字段 类型 是否必须 说明
header object 返回头信息
+err_no int 错误码,请求成功为200,请求错误时会返回400(参数错误)或500(服务内部错误)
+err_msg string 错误信息,请求成功为success;当请求错误时,如果是服务内部错误,会统一返回"服务器内部错误";如果是参数错误,则会返回具体的参数错误信息
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
result object 识别结果,请求失败时该参数为null
+face_liveness float 活体分数值
+thresholds object 由服务端返回最新的阈值数据(随着模型的优化,阈值可能会变化),将此参数与返回的face_liveness进行比较,可以作为活体判断的依据。误识率越低,准确率越高,相应的拒绝率也越高
++frr_1e-4 float 万分之一误识率的阈值
++frr_1e-3 float 千分之一误识率的阈值
++frr_1e-2 float 百分之一误识率的阈值
+face_list array 图片的详细信息描述
++face_token doube 人脸图片的唯一标识
++location object 人脸在图片中的位置
+++left double 人脸区域离左边界的距离
+++top double 人脸区域离上边界的距离
+++width double 人脸区域的宽度
+++height double 人脸区域的高度
+++rotation int64 人脸框相对于竖直方向的顺时针旋转角,[-180,180]
++face_probability double 人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大
++angle object 人脸旋转角度参数
+++yam double 三维旋转之左右旋转角[-90(左), 90(右)]
+++pitch double 三维旋转之俯仰角度[-90(上), 90(下)]
+++roll double 平面内旋转角[-180(逆时针), 180(顺时针)]
++quality object 人脸质量信息
+++blur double 人脸模糊程度,范围[0~1],0表示清晰,1表示模糊
+++illumination double 取值范围在[0~255], 表示脸部区域的光照程度 越大表示光照越好
+++completeness int64 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内

活体阈值参考

活体检测face_liveness的判断阈值选择,可参考下表

阈值(Threshold) 误拒率(FRR) 通过率(TAR) 攻击拒绝率(TRR))
0.05 0.01% 99.99% 97.75%
0.1 0.05% 99.95% 98.33%
0.3 (推荐 0.1% 99.9% 98.82%
0.5 0.5% 99.5% 99.67%
0.9 1% 99% 99.77%

概念介绍

  • 拒绝率(TRR):比如99%,指100次作弊假体识别,会有99次被拒绝。
  • 误拒率(FRR):比如1%,指1000次正常活体识别,会有10次因为活体分数低于阈值被错误拒绝。
  • 通过率(TAR):比如99%,指100次正常活体识别,会有99次因为活体分数高于阈值而通过。
  • 阈值(Threshold):高于此数值,则可判断为活体,推荐0.3。

身份核验接口

业务能力

  • 质量检测(可选):判断图片中是否包含人脸,以及判断人脸的姿态、遮挡、模糊、光照等是否符合识别条件,通过参数quality_control设置是否进行检测
  • 活体检测(可选):判断图片中的人脸是否为二次翻拍(如用户A用手机拍摄了一张包含人脸的图片1,用户B翻拍了图片1得到了图片2,并用图片2伪造成用户A去进行识别操作),通过参数liveness_control设置是否进行检测
  • 公安验证(必选):根据姓名和身份证号,从公安系统调取公民身份证小图,将指定的人脸图片与证件小图进行对比得到比对分数,基于对比分数判断是否为同一人。由于公安系统小图具有最权威的身份证明作用,对用户本人的验证结果可信度也最高。

  • 上述三项能力为顺序串行验证,接口默认返回公安身份对比分值,质量检测和活体检测为可选项。如果选择了这两项,则验证顺序为人脸质量检测->活体检测->公安身份验证。可以根据业务场景,选择这两项中的某一项或都不选择。
  • 如选择了前两个环节,则有任意一个条件不通过,则整个请求流程终止,并返回具体的错误信息。

推荐阈值

  • 此接口使用的对比算法,使用了针对带水纹证件照的专项模处理,可保证将水纹信息的影响降到尽可能低。

  • 如果比对成功,最终返回的有效数据为一个对比分值,在0~1之间,您可以设定具体的阈值来判断是否验证通过,推荐阈值为0.8,对应的误识率为万分之一。

    注意事项

    • 请求体格式化:Content-Type为application/json,通过json格式化请求体
    • Base64编码:图片的base64编码是指将图片数据编码成一串字符串,使用该字符串代替图像地址,首先得到图片的二进制,然后用Base64格式编码即可。注意:图片的base64编码是不包含图片头的,比如data:image/jpg;base64
    • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

HTTP请求方式

   post

请求参数

GET参数部分

参数名 必选 类型 说明
Action=PersonVerify string 固定此值
Version=2020-07-16 string API版本号,固定此值

Body参数格式

{
 "image_url":"https://www.zhibo8.cc/123.jpg",
 "id_card_number":"320103200001267529",
 "name":"窃.格瓦拉",
 "quality_control":"NORMAL",
 "liveness_control":"NORMAL"
 }

 或

 {
  "image_data":"adersfdfsafgf23...",
  "id_card_number":"320103200001267529",
  "name":"窃.格瓦拉",
  "quality_control":"NORMAL",
  "liveness_control":"NORMAL"
 }
参数 必选 类型 说明
image_url string 图片URL(image_url和image_data必须二选一,图片大小不超过2M)
image_data string Base64编码后的图片数据,编码后的图片大小不超过2M,图片尺寸不超过1920*1080
id_card_number string 身份证号码
name string 姓名(注:需要是UTF-8编码的中文)
quality_control string 图片质量控制,对应业务能力中的"质量检测"
NONE: 不进行控制
LOW:较低的质量要求
NORMAL: 一般的质量要求
HIGH: 较高的质量要求
默认 NONE
liveness_control string 活体检测控制 ,对应业务能力中的"活体检测"
NONE: 不进行控制
LOW:较低的活体要求(高通过率 低攻击拒绝率)
NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率)
HIGH: 较高的活体要求(高攻击拒绝率 低通过率)
默认NONE

输出

接口返回示例

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "cost": 1.092,
    "result": {
        "score": 94.503
    },
    "request_id": "\"123\""
}
参数 必选 类型 说明
header object 返回头信息
header.err_no int 错误码,请求成功为200,请求错误时会返回400(参数错误)或500(服务内部错误)
header.err_msg string 错误信息,请求成功为success;当请求错误时,如果是服务内部错误,会统一返回"服务器内部错误";如果是参数错误,则会返回具体的参数错误信息
cost double 请求耗时,单位:秒
result object 验证结果
result.score float 与公安小图相似度可能性,用于验证生活照与公安小图是否为同一人,有正常分数时为[0~100],推荐阈值80,超过即判断为同一人
request_id string 请求唯一标识

错误码说明

调用接口失败时,返回的HTTP消息体将中包含具体的错误信息,下表为错误码的具体说明,找不到错误原因时,可以联系我们,并提供Response中的RequestId/request_id,以便尽快解决问题。

签名错误码

错误代码(Code) 错误消息(Message) 状态码 说明
IncompleteSignature Date must be in ISO-8601 'basic format'. Got '%s'. See http://en.wikipedia.org/wiki/ISO_8601. 400 Date必须符合ISO_8601基本格式,参考:http://en.wikipedia.org/wiki/ISO_8601
IncompleteSignature KSC query-string parameters must include %s. Re-examine the query-string parameters. 400 查询条件中缺少签署信息,查询条件中必须包含”X-Amz-Algorithm“、”X-Amz-Credential“、”X-Amz-SignedHeaders“、”X-Amz-Date“信息
IncompleteSignature Unsupported ksc 'algorithm': %s. 400 只支持如下签名算法:AWS4-HMAC-SHA256
IncompleteSignature Authorization header requires 'Credential' parameter. Authorization=%s. 400 请求Authorization header中需要包含“Credential”参数
IncompleteSignature Credential must have exactly 5 slash-delimited elements, e.g. accesskeyid/date/region/service/aws4_request, got: %s. 400 请求Authorization header中中“Credential”至少包含5项以斜杠分隔的元素,如:keyid/date/region/service/aws4_request
IncompleteSignature Authorization header format error. 400 请求Authorization header的格式错误
IncompleteSignature Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header, Authorization=%s 400 请求中缺少“X-Amz-Date”或者“Date” header信息
IncompleteSignature Authorization header requires 'Signature' parameter. Authorization=%s 400 请求Authorization header中缺少“Signature”信息
IncompleteSignature Authorization header requires 'SignedHeaders' parameter. Authorization=%s 400 请求Authorization header中缺少“SignedHeaders”信息
MissingAuthenticationToken Request is missing 'Host' header. 403 请求header中缺少Host
MissingAuthenticationToken Request is missing Authentication Token. 403 请求header中缺少认证token
MissingAuthenticationToken %s not in Http Header. 403 %s不在Http header中
SignatureDoesNotMatch Host' must be a 'SignedHeader' in the Authorization. 403 请求的SignedHeader中必须包含Host
SignatureDoesNotMatch Credential should be scoped with a valid terminator: 'aws4_request', not: %s. 403 请求Authorization header中的“Credential”末尾必须是“aws4_request”
SignatureDoesNotMatch Credential should be scoped to a valid region, not:%s. 403 请求Authorization header中的“Credential”中的Region信息无效
SignatureDoesNotMatch Credential should be scoped to correct service: %s. 403 请求Authorization header中的“Credential”中的Service信息无效
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. 403 请求中提供的签名与实际计算结果不匹配
SignatureDoesNotMatch Signature expired:%s. 403 签名已过期
SignatureDoesNotMatch Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP. 403 请求Authorization header中的“Credential”中的Date应该是ISO8601基本格式,形如”YYYYMMDD“
InvalidClientTokenId The security token included in the request is invalid. 403 请求中提供的AccessKeyId无效

业务层级错误码

err_msg err_no 说明
未开通相应的服务 411 账号未开通服务权限
请求太频繁 510 QPS达到限制

其他说明

图片大小限制为5M,长宽像素不大于5000,图片下载时间限制为2.5s内,如果下载时间超过2.5s返回下载超时;

图片像素建议不小于256*256,太小可能会影响识别效果;

图片检测接口响应时间依赖图片的下载时间,请保证所检测图片所在的存储服务的稳定,图片建议使用金山云对象存储或者cdn做缓存等;

接口regionId仅支持cn-beijing-6;

金山云,开启您的云计算之旅

免费注册