接入文档
H5 lite方案（海外版）
API接口
获取比对结果
获取比对结果

# 调用URL

text
GET https://api-global.yljz.com/finauth/lite/get_result

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

说明：此接口提供活体结果反查功能，可以以 biz_id 为索引对 FinAuth H5 验证结果进行反查。该接口的调用信息保存有效期为一天，且仅支持3次调用。第4次或超过有效期调用则会返回错误信息，建议在每笔业务结束之后及时的取回数据。

# 参数

参数 必选/可选 类型 参数说明
api_key 必选 String 调用此API的api_key
api_secret 必选 String 调用此API的api_key的secret
biz_id 必选 String 通过 get_token、notify_url 或 return_url 返回的活体业务编号
return_verify_time 可选 String 该参数用于控制验证发生时间信息的返回
0（默认）：不返回做验证发生的时间
1：需要返回验证发生的时间
return_image 可选 String 此参数为可选参数，可在下面2种参数中选择，决定了是否返回活体图像数据：
  • 0（默认）：不需要图像
  • 1：需要返回最佳活体质量图（image_best）

# 返回值说明

参数 类型 说明
request_id String API 调用的流水号
status String 表示目前 FinAuth Lite 的使用状态：
NOT_STARTED get_token 之后，并没有调用过 do 方法，还没有开始验证
PROCESSING 正在进行 FinAuth Lite 验证
WEBRTC_UNSUPPORTED 表示浏览器不支持引起失败
OK 完成了 FinAuth Lite 验证（OK 并不表示通过了验证，是流程正常结束）
FAILED 验证流程未完成或出现异常
  • 注：在采用 "flash" 模式时，只要在照镜子环节30s内未通过验证，token状态即进入 FAILED 状态
CANCELLED 用户主动取消了验证流程
TIMEOUT 流程超时当处于 NOT_STARTED 或者 PROCESSING 状态时，liveness_result / verify_result 字段均不会返回 OK
fail_reason String get_token入参 get_fail_reason=1 时，可获取 "WEBRTC_UNSUPPORTED" 失败原因：
NETWORK_ERROR 因为网络问题无法连接
PERMISSIONS_ERROR 用户拒绝摄像头权限或浏览器（APP）不支持唤起摄像头权限
SUPPORT_ERROR 浏览器不支持 webRTC API 等 NETWORK_ERROR
biz_info Json 用户可以用此接口来传递一些额外信息
biz_id 业务流串号，可以用于反查比对结果
biz_no 客户业务流水号，会在 notify 和 return 时原封不动地返回给客户
biz_extra_data 在调用 notify_url 和 return_url 时会返回的额外数据
biz_id 业务流串号，可以用于反查比对结果
time_used Int 整个请求所花费的时间，单位为毫秒，此字段必定返回
liveness_result Json 活体检测结果；如果用户中途中断了活体流程，则此字段不返回。
result String 活体检测的结果，返回值分为两类：
  • PASS：活体检测通过
  • FAIL：活体检测失败
procedure_type String 返回本次活体所使用的活体验证方式
flash 通过炫彩活体方式进行活体验证
distance 通过距离活体方式进行活体验证
still 通过自拍一段人脸视频进行活体验证
details (flash) Json 活体检测结果的细节(procedure_type=flash)
FACE_NOT_FOUND 未检测到人脸次数
SIDE_FACE 未正对摄像头次数（偏转角不符合要求）
UPDOWN_FACE 未正对摄像头次数（俯仰角不符合要求）
EYE_OCCLUSION 遮挡眼部次数
MOUTH_OCCLUSION 遮挡嘴部次数
AWAY_FROM_CAMERA 过于远离摄像头次数
CLOSE_TO_CAMERA 过于靠近摄像头次数
FACE_OUT_OF_CAMERA 未正视摄像头次数
HIGH_BRIGHTNESS 光线过亮的次数
LOW_BRIGHTNESS 光线过暗的次数
LOW_FACE_QUALITY 视频中人脸质量太差的次数
details (distance) Json 活体检测结果的细节(procedure_type=distance)
FACE_NOT_FOUND 未检测到人脸次数
SIDE_FACE 未正对摄像头次数（侧脸）
UPDOWN_FACE 未正对摄像头次数（仰脸或低头）
EYE_OCCLUSION 遮挡眼部次数
MOUTH_OCCLUSION 遮挡嘴部次数
AWAY_FROM_CAMERA 过于远离摄像头次数
CLOSE_TO_CAMERA 过于靠近摄像头次数
FACE_OUT_OF_CAMERA 未正视摄像头次数
HIGH_BRIGHTNESS 光线过亮的次数
LOW_BRIGHTNESS 光线过暗的次数
LOW_FACE_QUALITY 视频中人脸质量太差的次数
details (still) Json 活体检测结果的细节(procedure_type=still且为上传视频模式时)
UPLOAD_TIMES 活体视频上传次数
FACE_NOT_FOUND 视频中没有检测到人脸的次数
LOW_FACE_QUALITY 视频中人脸质量太差的次数
INVALID_VIDEO_DURATION 视频时长不对的次数
SR_ERROR 语音识别结果有误的次数（静默活体可忽略）
NOT_SYNCHRONIZED 视频唇语识别错误的次数（静默活体可忽略）
NO_AUDIO 视频无声音的次数
VIDEO_FORMAT_UNSUPPORTED 视频格式错误的次数
VIDEO_FACE_INCONSISTENT 视频中出现了不一致的人脸
face_genuineness Json 表示对假脸攻击的判定，它包含四组置信度和阈值，均为实数取值 [0, 1] 区间。如果一个置信度大于其对应的阈值，则可以认为存在对应类型的假脸攻击
synthetic_face_confidence Float 合成脸的置信度
synthetic_face_threshold Float 合成脸的阈值
mask_confidence Float 面具的置信度
mask_threshold Float 面具的阈值
face_replacedInt 只取值 0 或 1。0 表示未检测出换脸攻击，1 表示检测出了换脸攻击。注意：该区域只有非rtc静默活体。
screen_replay_confidence Float 屏幕翻拍的置信度
screen_replay_threshold Float 屏幕翻拍的阈值
verify_result Json 人脸比对结果；如果用户中途中断了活体流程或 comparison_type 为 -1，则此字段不返回。
error_message String 在做人脸比对的时候出现错误
null 表示没有出现错误
NO_FACE_FOUND 对应的图像没有检测到人脸。此错误会产生计费
DATA_SOURCE_ERROR 调用比对数据发生错误，一般来说是数据出错。出现此错误时建议停止业务，并立即联系 FinAuth 客服或商务，待确认后再开启业务
INTERNAL_ERROR 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FinAuth 客服或商务
result_ref[x] 活体采集人像与上传的 image_ref[x] 的比对结果
confidence Float 综合分数的置信度，取值 [0, 100]，数字越大表示风险越小
thresholds Object 一组用于参考的置信度阈值，包含四个字段，取值 [0, 100]：
1e-3 Float 风险为千分之一的置信度阈值
1e-4 Float 风险为万分之一的置信度阈值
1e-5 Float 风险为十万分之一的置信度阈值
1e-6 Float 风险为百万分之一的置信度阈值
verify_time String 验证发生的时间戳（单位：秒），仅当 return_verify_time=1 时返回该字段
images Json 活体检测得到的图像，调用时通过 return_image 来选择，以 jpg 编码并用 base64 字符串返回，或返回为 null；当存在比对结果且比对结果中 error_message 为计费字段时，图像才会返回
  • image_best：质量最佳的活体图像
multifaces_tag String 仅当get_token的入参 return_multifaces_tag 参数为1时，返回此字段
  • 0：单人脸
  • 1：多人脸
multifaces_image String 如果 multifaces_tag=1，则返回一张包含多人脸的图像，以 jpg 编码并用 base64 字符串返回；如果 multifaces_tag=0，则返回空
device_risk_info Json 设备风险检测结果：
device_info_level String
none 表示未检测到风险
middle 表示中风险，需要人工复核
high 表示高风险，直接拦截
device_info_tags Json
is_cookies_disabled Int COOKIES 被禁用
is_code_tampered Int 代码被篡改
is_virtual_browser Int 虚拟浏览器
is_debug_mode Int 调试模式
is_higher_device_risk_threshold Int 高于设备风险阈值
visual_attributes Json 性别年龄预估结果
age Int 预估核验人活体图年龄
gender Int 预估核验人活体图性别，男：0，女：1
age_image_ref1 Int 预估比对参照人脸图年龄（仅 comparison_type=0 时返回）
gender_image_ref1 Int 预估比对参照人脸图性别，男：0，女：1（仅 comparison_type=0 时返回）
verify_risk_info Json 比对风险提示结果
verify_info_tags Json 表示活体图与比对图的比对风险
is_gender_risk
  • 0：表示活体图与比对图性别一致；
  • 1：表示活体图与比对图性别不一致
（comparison_type=0，则活体图与 ref1 图性别比对；comparison_type=-1，则返回为空）
is_age_risk
  • 0：表示活体图与比对图年龄差异不大（10岁以内）；
  • 1：表示活体图与比对图年龄差异较大（一般指的是年龄差距在10岁及以上，具体根据阈值设定。
（comparison_type=0，则活体图与 ref1 图年龄比对；comparison_type=-1，则返回为空）

# 示例

# biz_info 示例

json
{
    "biz_extra_data": "...",
    "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
    "biz_no": "cc47190f-5502-44a2-ab74-ea4f0f649f61"
}

# liveness_result 示例

json
{
    "result": "PASS/FAIL",
    "procedure_type": "video",
    "details": {
        "UPLOAD_TIMES": 5,
        "FACE_NOT_FOUND": 0,
        "LOW_FACE_QUALITY": 0,
        "INVALID_VIDEO_DURATION": 1,
        "SR_ERROR": 2,
        "NOT_SYNCHRONIZED": 1,
        "VIDEO_FORMAT_UNSUPPORTED": 0,
        "NO_AUDIO": 0
    },
    "face_genuineness": {
        "synthetic_face_confidence": 0.88,
        "synthetic_face_threshold": 0.5,
        "mask_confidence": 0.32,
        "mask_threshold": 0.5,
        "screen_replay_confidence": 0,
        "screen_replay_threshold": 0.5
    }
}

# verify_result 示例

json
{
    "verify_time": 1462259763,
    "result_ref1": {
        "confidence": 68.918,
        "thresholds": {
            "1e-3": 64,
            "1e-4": 69,
            "1e-5": 74,
            "1e-6": 79.9
        }
    }
}

# images 示例

json
{
    "image_best": "data:image/jpeg;base64,..."
}

# device_risk_info 示例

json
{
    "device_info_level": "none",
    "device_info_tags": {
        "is_cookies_disabled": "0",
        "is_higher_device_risk_threshold": "0",
        "is_debug_mode": "0",
        "is_virtual_browser": "0",
        "is_code_tampered": "0"
    }
}

# visual_attributes 示例

json
{
    "gender": 0,
    "age": 31,
    "age_image_ref1": 22,
    "gender_image_ref1": 0
}

# verify_risk_info 示例

json
{
    "verify_info_tags": {
        "is_gender_risk": 0,
        "is_age_risk": 0
    }
}

# 成功示例

json
{
    "request_id": "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c",
    "status": "OK",
    "biz_info": {
        "biz_extra_data": "...",
        "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
        "biz_no": "cc47190f-5502-44a2-ab74-ea4f0f649f61"
    },
    "liveness_result": {
        "procedure_type": "flash",
        "result": "PASS/FAIL",
        "details": {
            "UPLOAD_TIMES": 5,
            "FACE_NOT_FOUND": 0,
            "LOW_FACE_QUALITY": 0,
            "INVALID_VIDEO_DURATION": 1,
            "SR_ERROR": 2,
            "NOT_SYNCHRONIZED": 1,
            "VIDEO_FORMAT_UNSUPPORTED": 0,
            "NO_AUDIO": 0
        },
        "face_genuineness": {
            "synthetic_face_confidence": 0.88,
            "synthetic_face_threshold": 0.5,
            "mask_confidence": 0.32,
            "mask_threshold": 0.5,
            "screen_replay_confidence": 0,
            "screen_replay_threshold": 0.5
        }
    },
    "verify_result": {
        "result_ref1": {
            "confidence": 68.918,
            "thresholds": {
                "1e-3": 64,
                "1e-4": 69,
                "1e-5": 74,
                "1e-6": 79.9
            }
        }
    },
    "images": {
        "image_best": "data:image/jpeg;base64,..."
    },
    "time_used": 93
}

# 失败示例

json
{
    "error_message": "RESULT_NOT_FOUND",
    "request_id": "1462259901,fa79992d-ca61-48de-aa50-ea337c6aad42",
    "time_used": 4
}

# 错误码列表

# GetResult 特有的 ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
400 RESULT_NOT_FOUND 此错误类型表示传入的业务编号错误
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> 缺少某个必选参数
403 DATA_DESTROYED 超过可查询时间或超过最多可查询次数
400 BAD_ARGUMENTS:<key> 某个参数解析出错（比如必须是数字，但是输入的是非数字字符串；或者长度过长，etc.）
404 API_NOT_FOUND 所调用的API不存在
500 INTERNAL_ERROR 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FinAuth 客服或商务
Copyright © 2026 原力金智（重庆）科技有限公司