接入文档
RAW纯接口接入
炫彩活体
获取Token参数
获取Token参数

服务器请求Raw-GetToken接口,获取token参数,作为调用js-sdk的入参。

# Raw-GetToken

调用URL:

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

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

# 调用方法

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

入参


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

调用此API的api_key;

必选 api_secret String

调用此API的api_key的secret;

可选 biz_no String 用于标志一次验证流程,不超过128字符。如果要使用此参数,强烈建议对一次验证流程中调用的API(比如Raw-GetTokenFlash、Raw-GetResultFlash)使用同一个biz_no,对不同的验证流程使用不同的biz_no。
必选 color_number Int

本参数是炫彩活体过程中打光色彩数量,将根据您的设置返回相应数量的光序列

本参数允许设置的范围为:4,6,8

建议设置为:6

可选 liveness_preferences String

本参数用来设置活体检测的严格程度,可选参数设置如下:

  • ”none“:极速模式,默认设置
可选 procedure_type String

本参数用来指定活体方式

  • raw_flash:炫彩活体,目前只有一个选项
必选 comparison_type String

设定本次KYC服务的类型,目前支持的比对类型为“KYC验证”(取值“1”)或“人脸比对”(取值“0”)。传递其他值调用将识别,返回错误码400(BAD_ARGUMENTS)。

  • “1”表示KYC验证,表示将与参考照片比对,同时也可以与自己提供的照片(参数image_ref[x])比对;请注意:如果appkey没有KYC验证的权限,设置此值将返回错误码 403(AUTHORIZATION_ERROR:Denied);
  • “0”表示人脸比对,表示将与自己提供的照片(参数image_ref[x])比对。请注意:如果appkey没有人脸比对的权限,设置此值将返回错误码 403(AUTHORIZATION_ERROR:Denied)。
二选一:KYC验证时(comparison_type = 1) 必选 idcard_name String 需要核实对象的姓名,使用UTF-8编码。
必选 idcard_number String 需要核实对象的证件号码,也就是一个18位长度的字符串。
可选 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 = 0)   必选 uuid String 如果用户不使用参考数据进行比对,则上传此字段,用于标志本次识别对应的用户的唯一ID,要求不长于512字节。建议您对来自同一用户的比对请求使用同样的ID,这非常有利于您反查验证结果以及获得更好的数据报表查看体验。


必选 image_ref[x] File 多张由您自己提供的参照人脸照片。x表示此参数可重复多次,其中1<=x <= 2,即表示可以传最多两张参照人脸照片(参数分别为image_ref1、image_ref2)。如果在image_ref[x]中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将返回错误码400(MULTIPLE_FACES)。
可选 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:<param>)
  • “0”:取最大脸继续对比

注:本参数默认值为“0”,设置其他值时,会返回错误码400(BAD_ARGUMENTS)

必选 max_upload_times Int

本参数用于设置最大上传次数,允许设置范围为:2-5次

建议设置为:5(次)

必选 life_time Int

本参数用于设置token有效期,允许设置范围为:5-1440(单位:分钟),该参数决定了查询结果的有效期

建议设置为:60(分钟)


# 返回值说明

API返回的为一个JSON字符串。

字段 类型 说明
request_id String 用于区分每一次请求的唯一的字符串。除了发生错误404(API_NOT_FOUND)外,此字段必定返回。
biz_no String **此参数仅当调用时设置了biz_no参数才返回,即使API调用失败也返回,**值与传入的biz_no保持完全一致。
time_used Int 整个请求所花费的时间,单位为毫秒。除了发生错误404(API_NOT_FOUND)外,此字段必定返回。
token String 本字段仅调用成功时返回,仅用于作为Raw-ValidateFlash接口的参数,本字段不超过1024字节。**注意:**token有效期为根据传入参数确定
error_message String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节。否则此字段不返回。

# 通用的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>

某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.)

400 IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> 参数<param>对应的图像无法解析,有可能不是图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称。
400 NO_FACE_FOUND:<param> 表示上传的 image_ref 的图像中,没有检测到人脸。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称。
400 INVALID_IMAGE_SIZE<param> 客户上传的图像太大,具体是指像素尺寸的长或宽超过4096像素。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称。
400 NO_SUCH_ID_NUMBER KYC验证时,参考数据中没有此身份证号码的记录。

400

ID_NUMBER_NAME_NOT_MATCH

KYC验证时,参考数据中存在此身份证号码,但与提供的姓名不匹配。

400

INVALID_NAME_FORMAT

idcard_name参数字符数过多(多于32字符)、或者使用错误的编码(姓名要求以UTF-8编码)。

400

INVALID_IDCARD_NUMBER

idcard_number参数不是正确的身份证号码格式。身份证号码必定为18位数字,且最后一位可以是X(大小写均可)。

403

AUTHORIZATION_ERROR: <reason>

api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。

<reason>取值:

  • API_KEY_BE_DISCONTINUED:api_key被停用
  • IP_NOT_ALLOWED:不允许访问的IP(预留设计)
  • LIMIT_REACHED:这个api_key对当前API的调用量达到上限。仅当api_key为测试key
  • MORE_RETRY_TIMES:比对重试次数达到上限
  • NO_VERIFY_PERMISSION:没有人脸比对的权限,但是本次请求依然尝试调用了。
  • NO_DATA_SOURCE_PERMISSION:没有KYC验证的权限,但是本次请求依然尝试调用了。
  • DENIED:无权限调用当前API

  • 其他可能的错误码,请预留处理方案。
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制

404

API_NOT_FOUND

所调用的API不存在。

413 Request Entity Too Large

客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本,不是json格式。

500

INTERNAL_ERROR

服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务。



该文档未解决您的疑问?查看常见问题