接入文档
FaceID基础版
RAW纯接口接入
静默活体
上传录制视频进行活体验证
上传录制视频进行活体验证

# 描述

通过自拍一段人脸视频进行活体认证。上传视频成功后使用回传的标识token_still调用Raw-Verify接口进行比对和活体结果获取。

仅当appkey有使用API服务的静默活体验证权限时,才可以调用此API,否则返回错误码 403(AUTHORIZATION_ERROR:Denied)。

# 调用URL

https://api.megvii.com/faceid/lite/raw/validate_still

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

# 调用方法

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

# 参数

必选/可选 参数 类型 参数说明
必选 api_key String 调用此API的api_key
必选 api_secret String 调用此API的api_key的secret
必选 video File 需用户上传的视频,视频要求为ffmpeg所支持的格式及码率,视频建议时长为1~3秒,容量不大于20MB
可选 biz_no String 用于标志一次验证流程,不超过128字符。如果使用此参数,用于标志一次验证流程,不超过128字符。如果要使用此参数,强烈建议对一次验证流程中调用的API(比如Raw-GetRandomNumber、Raw-ValidateVideo、Raw-ValidateStill和Raw-Verify)使用同一个biz_no,对不同的验证流程使用不同的biz_no

可选

liveness_preferences

String

此本参数可选,表示一系列可以放松或加强活体检测的特别的选项 目前可用的选项有:

  1. “none”:表示没有特别的选项,此为默认值

  2. "still_strict":表示针对上传的视频进行相对严格的活体检测,此设置会提高安全性,但在一定程度上影响通过率

设置其他值,均会返回400(BAD_ARGUMENTS) 注:本参数对静默活体可用,视频活体严格程度的调节在verify接口中设置

可选

return_image

String

此参数为可选参数,决定了是否返回从视频中截取的最佳质量图像:

0(默认):不需要图像

1:需要返回1张最佳质量图 (仅当API调用成功后才返回)

2:需要返回2张最佳质量图 (仅当API调用成功后才返回)

可选 return_multifaces_tag String 是否返回活体采集过程中的多人脸标识:0:不返回(默认值),1:返回
可选 face_occlusion_detection String 用于设置是否开启人脸遮挡检测。0(默认):不开启;1:开启,如发生全程人脸遮挡,则活体不通过

可选

eye_close_detection

String

用于设置是否开启闭眼检测

0:不开启

1(默认值):开启,若用户全程闭眼,则活体不通过

可选

encryption_type

String

是否开启传输数据加密【加密对象:①validate_still接口的参数video,返回值image_best、image_best_2;②verify接口的参数idcard_name,idcard_number,image_ref[x]】,validate_still接口与verify接口均会根据此参数进行加密,加密详细说明详见--加密说明

0:否 (默认值)

1: SM2

2: RSA

# 返回值说明

字段 类型 说明
request_id String 用于区分每一次请求的唯一的字符串。此字段必定返回
time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回
biz_no String 此参数仅当调用时设置了biz_no参数才返回,但是如果设置了则即使API调用失败也返回,值与传入的biz_no保持完全一致
token_still String 本字段仅调用成功才返回,返回的token仅供Raw-Verify API使用。本字段不超过1024字节。注意:Token有效期为24小时
image_best String 本字段仅调用成功且return_image字段配置为1或者2时才返回,返回为将会用于人脸比对的视频中的最佳质量的人脸照片。采用Base64字符串返回,图像格式为JPEG。在异常情况下,该字段有可能返回null
image_best_2 String 本字段仅调用成功且return_image字段配置为2时才返回,返回为质量最佳的另一张活体图像。采用Base64字符串返回,图像格式为JPEG。在异常情况下(如只存在一张符合质量的图片),该字段有可能返回null
error_message String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节。否则此字段不存在

成功

{
  "time_used": 6206,
  "biz_no": "12345",
  "token_still": "68d32116d9ba2d2662812df30705dcb5",
  "request_id": "1491803871,dc23ec02-5ab5-48a4-8fe9-95f4eeb37699",
  "image_best": "data:image/jpeg;base64,..."
 
}

失败

{
  "time_used": 1,
  "error_message": "MISSING_ARGUMENTS: video",
  "request_id": "1491803987,5c52c7c6-e974-4c83-9f22-9d268d6e35b0"
}

# 错误码列表

Raw-ValidateStill API特有的 ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
400 VIDEO_FACE_NOT_FOUND 上传的视频中没有检测到人脸
400 VIDEO_LOW_FACE_QUALITY 上传的视频中人脸质量太差
400 VIDEO_INVALID_DURATION 上传的视频时长不对
400 VIDEO_UNSUPPORTED_FORMAT 视频无法解析,有可能是ffmpeg不支持的格式或视频有破损
400 VIDEO_FACE_OCCLUDE 上传的视频中人脸被遮挡

通用的ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
403 AUTHENTICATION_ERROR api_key 和 api_secret 不匹配
403 AUTHORIZATION_ERROR:<reason> api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。目前的<reason>有:• Denied (没有权限调用当前API)
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
400 MISSING_ARGUMENTS:<key> 缺少某个必选参数
400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 长度过长;不允许的输入值)

400

KEY_NOT_FOUND

没有配置密钥或者密钥不匹配导致,具体原因如下:

  • get_token的入参encryption_type开启加密(如该参数选择了1或者2,即SM2或者RSA),但未在控制台配置密钥
  • get_token的入参encryption_type选择的加密方式与控制台配置的密钥不一致,如encryption_type选择的是1,即SM2加密方式,而控制台配置密钥使用RSA加密方式
400 MESSAGE_ENCRYPTION_ERROR 云端对敏感信息加密失败
404 API_NOT_FOUND 所调用的API不存在
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系 FaceID 客服或商务
该文档未解决您的疑问?查看常见问题