接入文档
FaceID海外高级版（中文）
H5接入
API调用
获取Token
获取Token

# 1、接口地址

POST 注意：用 form-data 格式请求 https://api-idn.megvii.com/faceid/lite/get_token

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

说明：此接口提供FaceID H5验证服务，通过此接口客户可以获得一个token（token唯一且只能使用一次）。接口同时还能帮助完成人脸比对，并在完成验证后自动将人脸比对结果返回，方便集成开发。

# 2、入参说明

# 2.1、基础参数

必选／可选 参数 类型 参数说明
必选 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字节
可选 scene_id String 在控制台配置的对应使用场景的scene_id，用以自定义验证流程中的视觉元素 如果不传此参数，则选择在控制台中设置的默认scene 如果控制台中没有设定任何scene，则采用系统默认方案 如果传入了不存在的scene_id，调用将失败且返回错误码400（BAD_ARGUMENTS）
可选 language String 本参数可选，通过本参数可切换页面提示语言
  • 0：英语（默认）
  • 1：中文
  • 2：印尼语
  • 3：泰语
  • 4：菲律宾语
  • 5：越南语
  • 6：西班牙语
可选 procedure_type String 刷脸活体验证流程的选择。目前仅取以下值：
  • “flash”：通过炫彩活体方式进行活体验证。
  • "still"：通过自拍一段人脸视频进行活体认证。
本参数默认值为“flash”
可选 procedure_priority String 本参数可选，通过本参数配置不支持webrtc技术的降级方式
  • still：优先尝试still录制，如果不支持，降级到系统相机录制静默视频
  • keep：不进行降级，若遇到浏览器无法支持的情况，直接返回
默认值：
  • 当procedure_type为flash时，默认值是‘still’
设置其他值，均会返回错误码400（BAD_ARGUMENTS）
必选 comparison_type String 设定本次服务的类型，目前支持的比对类型为“人脸比对”（取值“0”）和“只活体不比对”（取值“-1”）。传递其他值调用将识别，返回错误码400（BAD_ARGUMENTS）
  • “0”表示人脸比对，FaceID将使用用户自己提供的照片（参数image_ref[x]）作为比对人脸照
  • “-1”表示只进行活体不进行比对
人脸比对时（comparison_type ＝ 0） 必选 uuid String 如果用户不使用参考数据进行比对，则上传此字段，用于标志本次识别对应的用户的唯一ID，要求不长于512字节。建议您对来自同一用户的比对请求使用同样的ID，这非常有利于您反查验证结果以及获得更好的数据报表体验
必选 image_ref[x] File 多张由您自己提供的参照人脸照片。x表示此参数可重复多次，其中1 <= x <= 2，即表示可以传最多二张参照人脸照片（参数分别为image_ref1, image_ref2） 如果在image_ref1、image_ref2中的任一张图片里没有找到人脸，将返回错误码400（NO_FACE_FOUND) 如果这些图片中任一张中有多张脸，将返回错误码400（MULTIPLE_FACES）
只进行活体不进行比对时（comparison_type ＝ -1） 必选 uuid String 用于标志本次活体对应的用户的唯一ID，要求不长于512字节。建议您对来自同一用户的比对请求使用同样的ID，这非常有利于您反查活体结果以及获得更好的数据报表体验

# 2.2、高级参数

可选 参数 类型 参数说明
可选 biz_extra_data String 在调用notify_url和return_url时会返回的额外数据，用户可以用此接口来传递一些额外信息，以帮助您调试和信息传递。此字段不超过4096字节
可选 get_shooting_error String 是否获取拍摄错误，本参数取值如下：
  • “1”： 获取长时间未上传录制视频错误
  • “0”：不获取长时间未上传视频错误
注：当本参数取值为“1”，且FaceID人脸验证过程中无法获取到用户拍摄的视频时，我们将会给return_url和notify_url中返回相应的错误信息：{"shooting_error":true/false}        当本参数取值为“0”时，即使FaceID人脸验证过程中无法获取到用户拍摄的视频，也不返回相应的错误信息        本参数默认取值为“0”
可选 maximum_shooting_time  int 用户点击开始拍摄后的超时时间设置，超过本时间后，用户界面将弹窗提示“长时间未收到录制视频”
注：本参数可选设置范围为2s-60s
       本参数默认设置为15s，建议设置时间为10-15s
可选 multi_oriented_detection String 决定对于image_ref[x]参数对应的图片，当检测不出人脸时，是否旋转90度、180度、270度后再检测人脸。本参数取值只能是 “1” 或 "0" （缺省值为“0”）:
  • 1：要旋转检测
  • 0：不旋转
  • 其他值：返回错误码400（BAD_ARGUMENTS）
请注意：设置此参数为1可能会轻微增加误检人脸的概率，如果您明确您的业务场景里不存在非正向的人脸图片、或概率极低，建议勿设置此参数
可选 fail_when_ref_multiple_faces String 用于设置参照人脸图（image_ref[x]）检测到多张人脸时，是否立刻返回错误，本参数取值如下：
  • 1：立即返回错误码400（MULTIPLE_FACES:）
  • 0：取最大脸继续对比
注：本参数默认值为“1”。
可选 return_multifaces_tag String 是否返回活体采集过程中的多人脸标识
  • 0：不返回（默认值）
  • 1：返回
可选 fmp_mode String 决定在活体检测结果中，是否进行云端假脸攻击判断，默认值为1
  •  1：在活体检测结果中，不进行云端假脸攻击判断（合成脸、面具攻击、屏幕翻拍），但返回假脸攻击具体分数。您可以根据自身业务需要，结合云端假脸攻击具体分数设计后续流程
  •  0：在活体检测结果中，判断云端假脸攻击情况
当您选择RTC方式的活体方式时（update_rtc），该字段不生效，即RTC类活体方式会始终进行云端假脸攻击判断
注：活体检测结果，请参见“Lite-GetResult”返回值的“liveness_result”段落
可选 get_fail_reason String 决定在WEBRTC_UNSUPPORTED时，是否返回失败原因（缺省值为“0”）
  • 1：获取失败原因
  • 0：不获取失败原因
可选 face_occlusion_detection String 用于设置是否开启人脸遮挡检测
  • 0（默认）：不开启；
  • 1：开启，如发生全程人脸遮挡，则活体不通过
可选 eye_close_detection String 用于设置是否开启闭眼检测
  • 0：不开启；
  • 1：开启
默认值：
  • 当procedure_type为flash时，默认值是‘1’
  • 当procedure_type为still时，默认值是‘1’
可选 action_http_method String 回跳到return_url的方式
  • POST（默认）：以form格式返回更为详细的数据，详见 回调说明；
  • GET：以return_url地址拼接参数的格式返回biz_id，详见 回调说明；
可选 redirect_type String 页面跳转模式（当redirect_type =1且action_http_method=GET时，支持点击浏览器或者操作系统的返回键可返回到进入lite之前的页面）
  • 0（默认）：不传或0，则正常跳转；
  • 1：页面使用 replace 方式跳转，不在浏览器 history 中留下记录；

# 3、返回结果

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

成功示例

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

失败示例

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

# 4、错误码列表

GetToken 特有的 ERROR_MESSAGE

HTTP状态代码 错误字段名称 值 说明
400 error_message IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> 参数<param>对应的图像无法正确解析，有可能不是一个图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意：<param>只会有一项，即第一个满足条件的名称
400 error_message NO_FACE_FOUND 表示上传的 image_ref[x] 的图像中，没有检测到人脸
400 error_message MULTIPLE_FACES 表示上传的 image_ref[x] 的图像中，检测到了多张人脸

通用的ERROR_MESSAGE

HTTP状态代码 错误字段名称 值 说明
403 error AUTHENTICATION_ERROR api_key 和 api_secret不匹配
403 error AUTHORIZATION_ERROR:<reason> api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。目前的<reason>有："Denied." :（没有权限调用当前API）"No data source permission." : （表示没有调用第三方联网核查）
403 error_message CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
400 error_message MISSING_ARGUMENTS:<key> 缺少某个必选参数
400 error_message BAD_ARGUMENTS:<key> 某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
404 error API_NOT_FOUND 所调用的API不存在
500 error_message INTERNAL_ERROR 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务
该文档未解决您的疑问？查看常见问题
Copyright © 2024 北京旷视科技有限公司