接入文档
PC接入
接口说明
获取Token
获取Token

URL:POST https://api.megvii.com/faceid/liveness/v2/get_token

**说明:**通过此接口客户可以获得一个用于网页端活体检测的token(token唯一且只能使用一次),只有通过token才能在后续调用活体检测接口。

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

# 参数列表

必选/可选 参数 类型 参数说明
必选 api_key String

调用此API的api_key

必选 api_secret String

调用此API的api_secret

必选 comparison_type String

确定本次活体服务为“人脸核身”或“人脸比对”,或者只进行活体不进行比对。取值只为“1”或“0”或“-1”。

  • “1”表示有人脸核身比对,将与参考照片进行比对。以下的“三选一”参数组里,必须使用“人脸核身”参数组。此外,如果没有“人脸核身”的权限,也不能设置此参数为“1”。  
  • “0”表示人脸比对,FaceID将使用用户自己提供的照片(参数image_ref[x])作为比对人脸照。以下的“三选一”参数集里,必须使用“人脸比对的”参数组。
二选一

人脸核身

comparison_type = “1”

必选 idcard_name String

需要核实身份对象的姓名,使用UTF-8编码。该参数用于在人脸核身时,配合idcard_number参数,从参考数据中获取人脸图像。

必选 idcard_number String 需要合适身份对象的证件号码,也就是一个18位长度的字符串。该参数用于在人脸核身时,配合idcard_name参数,从参考数据中获取人脸图像。
可选 image_ref[x] File

多张由您自己提供的参照人脸照片。x表示此参数可重复多次,其中1<= x <= 3,即表示可以传最多三张参照人脸照片(参数分别为image_ref1, image_ref2, image_ref3)。在人脸核身时使用这个参数,主要目的是让待验证照和您从其他渠道获得的照片比对(如:身份证拍摄照片、社保照片等等)。

如果在image_ref1、image_ref2、image_ref3中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将返回错误码400(MULTIPLE_FACES)。

人脸比对

comparison_type = “0”

必选 uuid String

人脸比对时,用于标志本次识别对应的用户的唯一ID,要求不长于512字节。建议您对来自同一用户的比对请求使用同样的ID,这非常有利于您反查活体和比对结果以及获得更好的数据报表体验。

必选 image_ref[x] File

多张由您自己提供的人脸照片。x表示此参数可重复多次,其中1<=x <= 3,即表示可以传最多三张人脸照片(参数分别为image_ref1, image_ref2, image_ref3)。

如果在image_ref1、image_ref2、image_ref3中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将返回错误码400(MULTIPLE_FACES)。

必选 return_url String

完成活体认证后网页跳转的目标URL。(回调方法为Post)


必选 notify_url String

完成活体认证之后,由FaceID服务器请求客户服务器的URL。(推荐为HTTPS页面,如果为HTTP则用户需要通过签名自行校验数据可信性,回调方法为Post)


必选 biz_no String

客户业务流水号,该号必须唯一。并会在notify和return时原封不动的返回给您的服务器,以帮助您确认每一笔业务的归属。此字段不超过128字节。


可选 biz_extra_data String

在调用notify_url和return_url时会返回的额外数据,用户可以用此接口来传递一些额外信息,以帮助您调试和信息传递。此字段不超过4096字节。


可选 scene_id String

在控制台配置的对应使用场景的scene_id,如果不传此参数,则选择在控制台中设置的默认scene。

可选 screen_replay String

表示是否开启屏幕翻拍检测。

  • 0:默认值,不开启屏幕翻拍的检测
  • 1:开启屏幕翻拍检测(若检测屏幕翻拍,返回值将增加屏幕翻拍的结果返回)

注:由于PC端的某些摄像头的驱动,自带增加摄像头视频特效等功能。开启屏幕翻拍检测之后,有可能导致误检增加。

可选 multi_oriented_detection String 对image_ref[x]参数启用图片旋转检测功能。当image_ref[x]参数中传入的图片未检测到人脸时,是否对图片尝试旋转90度、180度、270度后再检测人脸。本参数取值只能是 “1” 或 "0" (缺省值为“0”):
  • “1”:启用旋转检测(启用旋转检测后,会增加API的调用时间)

  • “0”:不启用旋转检测

  • 其他值:返回错误码400(BAD_ARGUMENTS)

注意:设置此参数为1可能会轻微增加误检人脸的概率,如果您明确您的业务场景里不存在非正向的人脸图片、或概率极低,建议勿设置此参数。

注:以上参数名标红表示为本次更新新增字段

# 返回结果

字段 类型 说明
request_id String 用于区分每一次请求的唯一的字符串。此字符串可以用于后续数据反查。此字段必定返回。
time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回。
token String 一个字符串,可用于DoLiveness接口,调用DoLiveness时传入此参数,即可按照上述配置进行活体检测。(注:每个token只能被使用一次)
expired_time Int 一个时间戳,表示token的有效期。
error_message String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节。否则此字段不存在。

成功

{`` ``"time_used"``: 5,`` ``"token"``: ``"34fb21937e47ae719f11cbc719615687"``,`` ``"request_id"``: ``"1462257147,3149525e-2c24-4862-8e9f-92040595f0a4"``,`` ``"expired_time"``: 1462257765``}

失败

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

# 错误码列表

GetToken 特有的 ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
400 IMAGE_ERROR_UNSUPPORTED_FORMAT: 参数对应的图像无法正确解析,有可能不是一个图像文件、或有数据破损。为 image_ref1、 image_ref2、 image_ref3中的一个。请注意:只会有一项,即第一个满足条件的名称。
400 INVALID_NAME_FORMAT 人脸核身时,idcard_name参数字符数过多(多于32字符)、或者使用错误的编码(姓名要求以UTF-8编码)。
400 INVALID_IDCARD_NUMBER 人脸比对时,idcard_number参数不是正确的证件号码格式。证件号码必定为18位数字,且最后一位可以是X(大小写均可)。

通用的ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
403 AUTHENTICATION_ERROR api_key和api_secret不匹配。
403 AUTHORIZATION_ERROR: api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。目前的有:
"Denied." : (没有权限调用当前API)
"No data source permission. " :(仅为FaceID Verify API存在,表示使用“人脸核身”的方式调用FaceID Verify API,但是没有“人脸核身”的权限)
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制。
400 MISSING_ARGUMENTS: 缺少某个必选参数。
400 BAD_ARGUMENTS: 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.)
404 API_NOT_FOUND 所调用的API不存在。
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务。
该文档未解决您的疑问?查看常见问题