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

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

# 调用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（分钟）
可选 return_multifaces_tag String 是否返回活体采集过程中的多人脸标识
  • 0：不返回（默认值）
  • 1：返回
可选 face_occlusion_detection String 用于设置是否开启人脸遮挡检测。0（默认）：不开启；1：开启，如发生全程人脸遮挡，则活体不通过
可选 encryption_type String 是否开启传输数据加密【加密对象：①get_token接口的参数idcard_name、idcard_number、image_ref[x]；②get_result接口的参数image_best、image_best_2】，get_token接口与get_result接口均会根据此参数进行加密，加密详细说明详见-- 加密说明
  • 0：不开启（默认）
  • 1：SM2
  • 2：RSA

# 返回值说明

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（大小写均可） 否
400 KEY_NOT_FOUND 没有配置密钥或者密钥不匹配导致，具体原因如下：
  • get_token的入参encryption_type开启加密（如该参数选择了1或者2，即SM2或者RSA），但未在控制台配置密钥
  • get_token的入参encryption_type选择的加密方式与控制台配置的密钥不一致，如encryption_type选择的是1，即SM2加密方式，而控制台配置密钥使用RSA加密方式
否
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客服或商务 否

该文档未解决您的疑问？查看常见问题
Copyright © 2024 北京旷视科技有限公司