›KYC验证/人脸比对

KYC验证/人脸比对

  • 产品介绍
  • 计费说明
  • SDK-接入文档(android版)
  • SDK-接入文档(ios版)
  • SDK-获取BizToken
  • SDK-验证接口
  • SDK-错误码说明
  • H5接入说明
  • 小程序接入说明

身份证识别

  • 产品介绍
  • 计费说明
  • SDK接入文档(Android版)
  • SDK接入文档(ios版)
  • 错误码说明
  • H5接入说明
  • 小程序接入说明
  • API接入说明

鉴权说明

  • 鉴权说明

FAQ

  • 充值相关
  • SDK集成相关

H5接入说明

H5接入流程

  • 通过get_biz_token API接口,设置参数,并获取biz_token。
  • 页面跳转到FaceID H5页面进入验证流程。
  • 验证流程结束后,可以通过get_result接口获取本次验证流程的详细信息。

下面对各个步骤进行详细的说明。

第1步:获取biz_token

API名称

Get_biz_token

说明

客户服务器端通过此接口可以获得一个biz_token(biz_token唯一且只能使用一次,有效期为1小时,但是您可以在1天内对该结果进行查询)。该请求是POST方法,参数中要包括用户后续验证的相关信息。

API地址

POST https://api.megvii.com/faceid/lite/get_token

参数

参数名可选/必选类型说明
api_key必选String调用此API的api_key
api_secret必选String调用此API的api_key的secret
return_url必选String用户完成或取消验证后网页跳转的目标URL。(回调方法为Post)
notify_url必选String用户完成验证、取消验证、或验证超时后,由FaceID服务器请求客户服务器的URL。(推荐为HTTPS页面,如果为HTTP则用户需要通过签名自行校验数据可信性,回调方法为Post)注:出于安全性考虑,FaceID服务对服务器端回调端口有白名单要求,支持的端口有:443,5000,16003,8883,8028。
biz_no必选String客户业务流水号,该号必须唯一。并会在notify和return时原封不动的返回给您的服务器,以帮助您确认每一笔业务的归属。此字段不超过128字节。
biz_extra_data可选String在调用notify_url和return_url时会返回的额外数据,用户可以用此接口来传递一些额外信息,以帮助您调试和信息传递。此字段不超过4096字节。
web_title可选String验证网页展示用的标题文字。此字段不超过32字节,但考虑到显示效果,建议控制在10个中文字符以内。此参数默认为空,此时系统将采用默认的标题。
liveness_preferences可选String本参数可选,通过一系列配置项来调节活体检测的严格度。目前可用的选项有:
“none”:表示没有特别的选项,此为默认值。
"video_strict":表示针对上传的视频进行相对严格的活体检测,此设置会提高安全性,但在一定程度上影响通过率。
注意:设置其他值,均会返回400(BAD_ARGUMENTS)。
comparison_type必选Int本次验证服务的类型。
0:表示活体照片和上传照片进行比对(人脸比对)
1:表示活体照片和参考数据进行比对(KYC验证)
idcard_mode条件必选String当comparison_type=1,必须传入此字段。传递参数“0”,“1”,“2”,“3”或“4”,表示获取用户身份证信息的方法。传递其他值调用将识别,返回错误码400(BAD_ARGUMENTS)。
0:不拍摄身份证,而是通过 idcard_name / idcard_number 参数传入;
1:仅拍摄身份证人像面,可获取人像面所有信息;
2:拍摄身份证人像面和身份证国徽面,可获取身份证所有信息;
3:不拍摄身份证,但会要求用户在界面上输入身份证号和姓名;
4:拍摄身份证人像面或用户输入身份证号和姓名,用户可在界面上自行选择身份证录入方法。
idcard_uneditable_field条件可选String选择用户不可编辑的字段。当选择拍摄身份证来获取上面的文字信息时,会由于OCR算法的问题导致文字识别不准确(如:生僻字、形近字),通过该参数可以限制用户对识别得到的结果进行编辑。(如:身份证号的识别都是准确的,可以限制用户不能编辑此字段)。
目前可以选为不可修改的字段有 姓名(idcard_name),身份证号(idcard_number),身份证有效期(idcard_valid_date),签发机关(idcard_issued_by)。传递参数时用逗号隔开,可以同时设置多个参数。例子:idcard_uneditable_field=idcard_number,idcard_valid_date 表示身份证号和过期时间都不可编辑,如果尝试编辑则会提示需要重新拍摄。传入其他值或格式不对,本次调用将失败,返回错误码400(BAD_ARGUMENTS)。
本参数默认值为空,表示所有字段都可以编辑。本参数默认值为空,表示所有字段都可以编辑。
idcard_name条件必选String姓名。当comparison_type=1,必须传入此字段
idcard_number条件必选String身份证号。当comparison_type=1, 必须传入该字段
uuid条件必选String当comparison_type=0时,该字段用于标志本次识别对应的用户的唯一ID,要求不长于128字节。建议对来自同一用户的比对请求使用同样的ID。
image_ref1条件必选File由您自己提供的参照人脸照片,File类型。当comparison_type=0时,必选。
image_ref2可选File由您自己提供的参照人脸照片,File类型
multi_oriented_detection可选String决定对于image_ref[x]参数对应的图片,当检测不出人脸时,是否旋转90度、180度、270度后再检测人脸。本参数取值只能是 “1” 或 "0" (缺省值为“0”):
“1”:要旋转检测;
“0”:不旋转; 其他值:返回错误码400(BAD_ARGUMENTS)
fmp_mode可选String决定在活体检测结果中,是否进行云端假脸攻击判断,默认值为1。
1:在活体检测结果中,不进行云端假脸攻击判断(合成脸、面具攻击、屏幕翻拍),但返回假脸攻击具体分数。您可以根据自身业务需要,结合云端假脸攻击具体分数设计后续流程。
0:在活体检测结果中,判断云端假脸攻击情况。

返回结果

字段类型说明
request_idString用于标示本次请求的唯一的字符串,总返回该字段
time_usedInt整个请求所花费的时间,单位为毫秒,总返回该字段
tokenString一个字符串,可用于DoVerification接口,调用DoVerification时传入此参数,即可按照上述配置进行活体检测。
(注:每个token只能被使用一次)
biz_idString业务流串号,可以用于反查比对结果。
expired_timeInt一个时间戳,表示token的有效期。
error_messageString错误原因,请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明。

错误说明

error字段可能的错误包括:

error说明HTTP状态码
IMAGE_ERROR_UNSUPPORTED_FORMAT: 参数对应的图像无法正确解析,有可能不是一个图像文件、或有数据破损。为 image_ref1、 image_ref2中的一个。请注意:只会有一项,即第一个满足条件的名称。400
NO_FACE_FOUND表示上传的 image_ref[x] 的图像中,没有检测到人脸。400
MULTIPLE_FACES表示上传的 image_ref[x] 的图像中,检测到了多张人脸。400
INVALID_NAME_FORMATKYC验证时,idcard_name参数字符数过多(多于32字符)、或者使用错误的编码(姓名要求以UTF-8编码)。400
INVALID_IDCARD_NUMBERKYC验证时,idcard_number参数不是正确的身份证号码格式。身份证号码必定为18位数字,且最后一位可以是X(大小写均可)。400
MISSING_ARGUMENTS:缺少某个必选参数(参数名为key)400
BAD_ARGUMENTS:某个参数(参数名为key)解析出错400
AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。403
AUTHORIZATION_ERROR:鉴权失败,例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
CONCURRENCY_LIMIT_EXCEEDED请求超过并发403
API_NOT_FOUND所调用的API不存在。404
INTERNAL_ERROR内部错误500

示例

返回结果示例:成功

{
    "time_used": 5,
    "token": "34fb21937e47ae719f11cbc719615687",
    "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "expired_time": 1462257765
}

返回结果示例:return_url没填导致的错误

{
    "error_message": "BAD_ARGUMENTS: return_url",
    "request_id": "1461740007,71eeb124-08f0-47b3-8fc8-ac048cfa1372",
    "time_used": 4
}

第2步:跳转URL

API名称

DoVerification

说明

此接口提供 FaceID Lite 验证服务,通过 GetToken 接口获得 token,可利用此接口转跳到对应的网页验证。

API地址

GET https://api.megvii.com/faceid/lite/do

参数

参数名可选/必选类型说明
token必选string由get_token返回的token。

返回及其他说明

此接口调用返回一个Web页面,所有的错误信息均通过可视化的Web页面返回。

第3步:Return_url 和 Notify_url 回调

说明

客户在GetToken方法中传入的 return_url 和 notify_url 会在完成 FaceID Lite 验证后被系统回调。其中

  1. return_url:会通过Post方法回调,直接通过页面跳转实现;
  2. notify_url:会通过Post方法回调,有FaceID后台发起调用。出于安全性考虑,FaceID服务对服务器端回调端口有白名单要求,支持的端口有:443,5000,16003,8883,8028;(如果回调地址不是HTTPS的,则推荐进行签名校验)

回调的内容为一个Json数据,具体的内容如下表所示。

参数

参数名类型说明
datastring验证返回值,具体见“”FaceID Lite 返回值说明
signstring数据段的签名,签名方法为 sign = sha1(API_SECRET + json_data),其中sha1返回的字符均为小写。

第4步(可选):获取验证详细信息

API名称

get_result

说明

验证流程结束后,用户服务器可以调用get_result接口,获取本次验证的详细信息。

API地址

GET https://api.megvii.com/faceid/lite/get_result

参数

参数名可选/必选类型说明
api_key必选String调用此API的api_key;
api_secret必选String调用此API的api_key的secret;
biz_id必选String通过 get_token, notify_url 或者 return_url 返回的活体业务编号。
return_image可选String此参数为可选参数,可在下面三种参数中选择,决定了是否返回活体图像数据:
0(默认):不需要图像
1:需要返回最佳活体质量图
2:需要返回身份证人像面图像
3:需要返回身份证国徽面图像
4:需要返回所有图像

返回结果

返回值说明

返回值说明见“FaceID Lite 返回值说明”表格。

错误码列表

error说明HTTP状态码
RESULT_NOT_FOUND此错误类型表示传入的业务编号错误。400
IMAGE_ERROR_UNSUPPORTED_FORMAT: 参数对应的图像无法正确解析,有可能不是一个图像文件、或有数据破损。为 image_ref1、 image_ref2中的一个。请注意:只会有一项,即第一个满足条件的名称。400
NO_FACE_FOUND表示上传的 image_ref[x] 的图像中,没有检测到人脸。400
MULTIPLE_FACES表示上传的 image_ref[x] 的图像中,检测到了多张人脸。400
INVALID_NAME_FORMATKYC验证时,idcard_name参数字符数过多(多于32字符)、或者使用错误的编码(姓名要求以UTF-8编码)。400
INVALID_IDCARD_NUMBERKYC验证时,idcard_number参数不是正确的身份证号码格式。身份证号码必定为18位数字,且最后一位可以是X(大小写均可)。400
MISSING_ARGUMENTS:缺少某个必选参数(参数名为key)400
BAD_ARGUMENTS:某个参数(参数名为key)解析出错400
AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。403
AUTHORIZATION_ERROR:鉴权失败,例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
CONCURRENCY_LIMIT_EXCEEDED请求超过并发403
DATA_DESTROYED超过可查询时间或超过最多可查询次数403
NON_ENTERPRISE_CERTIFICATION客户未进行企业认证403
BALANCE_NOT_ENOUGH余额不足403
ACCOUNT_DISABLED账户已停用403
API_NOT_FOUND所调用的API不存在。404
INTERNAL_ERROR内部错误500

附:FaceID Lite返回值说明

字段类型说明
request_idString用于标示本次请求的唯一的字符串,总返回该字段
time_usedInt整个请求所花费的时间,单位为毫秒,总返回该字段
statusString表示目前 FaceID Lite 的使用状态:
NOT_STARTED:get_token 之后,并没有调用过 do 方法,还没有开始验证;
PROCESSING:正在进行 FaceID Lite 验证;
OK:完成了 FaceID Lite 验证(OK并不表示通过了验证,是流程正常结束);
FAILED:验证流程未完成或出现异常;
CANCELLED:用户主动取消了验证流程;
TIMEOUT:流程超时。传入的biz_token,原样返回
(当处于“NOT_STARTED”或者“PROCESSING”状态时,idcard_info / liveness_result /verify_result字段均不会返回。之前在get_biz_token中设置的biz_no字段,如果没有设置,返回为空字符串
biz_infoJson包含:biz_id, biz_no, biz_extra_data
biz_id:业务流串号,可以用于反查比对结果; biz_no:客户业务流水号,会在notify和return时原封不动的返回给客户; biz_extra_data:在调用 notify_url 和 return_url 时会返回的额外数据,
用户可以用此接口来传递一些额外信息。
idcard_infoJson身份证识别的结果,此字段在 idcard_mode = 0 时不返回;如果用户中途中断了活体流程,则此字段也不返回。
内容包括:
idcard_mode:表示 get_token 时选择的 idcard_mode;
idcard_uneditable_feild:表示 get_token 是选择的 idcard_uneditable_feild;
idcard_mode_user:该字段仅在idcard_mode=4时返回,表示用户选择的身份证信息录入模式 0:选择拍摄身份证人像面; 1:选择手输身份证信息;
idcard_number:表示最终经过用户确认的身份证号 (根据idcard_uneditable_feild可能被修改过);
idcard_name:表示最终经过用户确认的姓名 (根据idcard_uneditable_feild可能被修改过);
idcard_valid_date:表示最终经过用户确认的身份证有效期 (根据idcard_uneditable_field可能被修改过,如果不用拍摄身份证国徽面则不返回此字段);
idcard_issued_by:表示最终经过用户确认的身份证签发机关 (根据idcard_uneditable_field可能被修改过,如果不用拍摄身份证国徽面则不返回此字段);
front_side:身份证人像面的识别结果(如果不用拍摄身份证人像面则不返回此字段);
ocr_result:文字识别结果;
upload_times:在FaceID Lite验证流程中身份证人像面上传的次数;
back_side:身份证国徽面的识别结果(如果不用拍摄身份证国徽面则不返回此字段);
ocr_result:文字识别结果;
upload_times:在FaceID Lite验证流程中身份证国徽面上传的次数;
ocr_front_quality:身份证人像面各字段质量判断及逻辑判断结果;
ocr_back_quality:身份证国徽面各字段质量判断及逻辑判断结果;
liveness_resultJson活体检测结果;如果 face_genuineness:表示对假脸攻击的判定,它包含四组置信度和阈值,均为实数取值[0,1]区间。如果一个置信度大于其对应的阈值,则可以认为存在对应类型的假脸攻击。用户中途中断了活体流程,则此字段不返回。
result:活体检测的结果,返回值分为两类:
PASS:活体检测通过; FAIL:活体检测失败;
注:
当fmp_mode为"0",该字段会考虑云端假脸攻击情况(即:face_genuineness字段)。当云端假脸攻击被检测出来时,会返回FAIL;
当fmp_mode为"1",该字段不会考虑云端假脸攻击情况。当云端假脸攻击被检测出来时,会返回PASS。不过,您依然可以根据自身的业务,并结合”face_genuineness“字段所返回的分数进行相关的业务判断。

details:活体检测结果的细节:

UPLOAD_TIMES:<活体视频上传次数>;
FACE_NOT_FOUND:<视频中没有检测到人脸的次数>;
LOW_FACE_QUALITY:<视频中人脸质量太差的次数>;
INVALID_VIDEO_DURATION:<视频时长不对的次数>;
SR_ERROR:<语音识别结果有误的次数>;
NOT_SYNCHRONIZED:<视频唇语识别错误的次数>;
NO_AUDIO:<视频无声音的次数>;
VIDEO_FORMAT_UNSUPPORTED:<视频格式错误的次数>;


face_genuineness:表示对假脸攻击的判定,它包含四组置信度和阈值,均为实数取值[0,1]区间。如果一个置信度大于其对应的阈值,则可以认为存在对应类型的假脸攻击。
synthetic_face_confidence:<合成脸的置信度>
synthetic_face_threshold:<合成脸的阈值>
mask_confidence:<面具的置信度>
mask_threshold:<面具的阈值>
screen_replay_confidence:<屏幕翻拍的置信度>
screen_replay_threshold:<屏幕翻拍的阈值>
verify_resultJson人脸比对结果;如果用户中途中断了活体流程,则此字段不返回。
error_message:在做验证的时候出现错误
null:表示没有出现错误
NO_SUCH_ID_NUMBER:KYC验证时,参考数据中没有此身份证号码的记录。此错误会产生计费。
ID_NUMBER_NAME_NOT_MATCH:KYC验证时,参考数据中存在此身份证 号码,但与提供的姓名不匹配。此错误会产生计费。
IMAGE_ERROR_UNSUPPORTED_FORMAT: data_source:KYC验证时,姓名和身份证号已经通过核查。但图片无法解析、或者没有图片。此错误会产生计费。
DATA_SOURCE_ERROR:KYC验证时调用参考数据发生错误,一般来说是参考数据出错。出现此错误时建议停止业务,并立即联系FaceID客服或商务,待 确定参考数据正常后再开启业务。
INTERNAL_ERROR:服务器内部错误,当此类错误发生时请再次请求,如 果持续出现此类错误,请及时联系FaceID客服或商务。

result_faceid:KYC验证的综合分数;
"confidence": 综合分数,Float类型,取值[0,100], 数字越大表示风险越小。
“thresholds”:一组用于参考的置信度阈值,Object类型, 包含四个字段,均为Float类型、取值[0,100]:
“1e-3”:风险为千分之一的置信度阈值;
“1e-4”:风险为万分之一的置信度阈值;
“1e-5”:风险为十万分之一的置信度阈值;
“1e-6”:风险为百万分之一的置信度阈值。

result_ref[x]:活体采集人像与上传的image_ref[x]的比对结果;(同result_faceid)

result_idcard_photo:活体采集人像与身份证照片上的人脸比对的结果;(同result_faceid)

id_exceptions: 返回身份相关的异常情况,如身份证号码是否曾被冒用来攻击FaceID活体检测、参考数据人像照片是否存在质量不佳等问题。调用者可通过此对象增进对比对结果的解读。本对象仅在KYC验证时(comparison_type == 1)返回,返回包含如下字段:
"id_attacked":Int类型,判别身份证号码是否曾被冒用来攻击FaceID活体检测, 取值1表示曾被攻击、取值0表示未被攻击。攻击形态包括但不限于戴面具、换人 攻击、软件3D合成人脸等手段。若被判别为“是”,则有可能这个身份证号码目前 存在被利用的风险。注意:判别为“是”不意味身份持有者本人参与攻击,有可能 其身份被他人盗用而本人无感知。
"id_photo_monochrome":Int类型,参考数据人像照片的色彩判断,取值1表示 是黑白照片、取值0表示是彩色照片。参考数据存在一部分人像照片是黑白的现象, 黑白的照片会影响比对质量,一般来说将降低比对分数。本字段表达这样的异常。
imagesJson活体检测得到的图像,调用时通过 return_image 来选择,或以jpg编码并用base64字符串返回,或返回为null。
只有当 status 返回字段为 "OK" 时,图像才会返回。
image_best:质量最佳的活体图像; image_idcard_back:最后一次上传的身份证国徽面;
image_idcard_front:最后一次上传的身份证人像面。
注意:此字段仅在get_result接口调用时才会返回有图像信息,在notify_url和return_url不返回图片数据信息

当前版本

  • v1.1.0

历史版本

  • v1.0.0 文档
  • v0.1.0 文档
← SDK-错误码说明小程序接入说明 →