腾讯云人脸核身对接使用完全指南：从开通到生产级部署

apphuang2026年06月26日 13:04:583

1. 产品概述：选择适合你的人脸核身方案

腾讯云慧眼人脸核身是一组对用户身份信息真实性进行验证审核的服务套件，提供人脸核身、身份信息核验、银行卡要素核验和运营商类要素核验等各类实名信息认证能力。该产品广泛应用于金融、运营商、共享出行等领域，帮助业务方远程、快速、准确地完成用户身份核验。

目前腾讯云慧眼人脸核身服务分为八大子产品，开发者需要根据自身的业务场景和安全需求选择合适的产品：

1.1 Plus 版人脸核身

Plus版在增强版的基础上，新增了多模态大模型、黑产模板批量识别、模型自学习、智能审核等高级安全功能。它能够有效拦截传统活体检测模型无法识别的AIGC合成攻击以及黑产批量的模板注入攻击。适用于金融、运营商、出行等行业的移动支付、用户注册、信息变更等核心场景。

1.2 增强版人脸核身

增强版在基础版的基础上，通过设备安全增强、活体安全增强、智能分级认证增强，全面升级核身安全能力。它能够在刷脸核身的同时实时检测当前设备的风险，根据风险等级智能选择认证方式，有效拦截摄像头劫持、恶意注入等多种攻击方式。适用于金融、保险、电商、直播、社交等行业的实名注册、密码修改、交易提现场景。

1.3 基础版人脸核身

基础版是一套集成了证件OCR识别、活体检测和人脸比对三大功能的身份信息验证业务流程。验证通过率高、稳定性强，秒级确认用户身份。适用于金融、保险、共享出行等远程实名或在线核验身份的场景。

1.4 意愿核身

意愿核身结合增强版人脸核身与语音AI能力，用户只需对准摄像头拍摄人脸视频并进行语音朗读或语音问答，即可完成本人真实身份的认证以及真实意愿的确认。产品已支持App、H5、小程序多个渠道的接入。

1.5 实名信息核验

实名信息核验是对用户身份信息真实性进行验证的基础方式，对姓名、身份证号、手机号、银行卡号等信息进行真实性和一致性的核验。适用于社交娱乐、在线游戏实名认证、主播实名核验等场景。

此外还有E证通（基于微信小程序的网络身份信息核验服务）和实证NFC（使用手机NFC功能读取证件加密信息）等产品，开发者可根据实际需求选择。

2. 接入前的准备工作

2.1 账号注册与实名认证

接入腾讯云人脸核身服务的第一步是注册腾讯云账号并进行企业实名认证。申请开通人脸核身服务需要腾讯云账号为企业实名用户。个人账号无法申请开通人脸核身服务。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2.2 开通人脸核身服务

完成企业实名认证后，打开腾讯云人脸核身产品介绍页，单击页面上的申请免费试用，填写具体业务需求，提交接入申请即可开通服务。开通后，登录人脸核身控制台，阅读并同意服务条款，单击立即开通，即可获得人脸核身的API接口调用权限。

2.3 购买资源包

人脸核身默认是按量计费模式（后付费），也可以购买资源包（预付费）。购买资源包后，会优先抵扣资源包，资源包抵扣完后自动转为按量计费。建议在正式接入前根据业务预估量购买合适的资源包，以降低单位调用成本。

2.4 确认小程序类目与资质（如适用）

如果业务需要通过微信小程序或微信原生H5接入人脸核身，则需要确认公众号或小程序的主体和类目是否符合要求。接入前请登录微信公众平台，确认小程序服务类目满足要求，并准备好对应的资质文件。资质审核需要5到7个工作日，请预留好上线时间。

支持的行业类目包括：政务（机构或事业单位）、金融（银行、保险、信托、基金、证券/期货、持牌消费金融）、医疗（公立医疗机构、公立互联网医院、三级私立医院机构）、运营商（基础电信运营商、增值电信运营商）、教育（学历教育、公立/私立教育机构）、出行与交通（网约车、航空、地铁、火车、公交等）、生活服务、旅游、商业服务（公证）、社交（直播）、快递与邮政等。

3. 人脸核身接入方式总览

腾讯云人脸核身支持多种接入方式，主要分为SaaS模式和PaaS模式两大类。

3.1 SaaS模式

SaaS模式提供了封装好的核身页面和流程，开发者只需进行简单的配置和集成即可使用。支持的接入渠道包括：

微信HTML5接入（微信公众号H5、微信浮层H5）
微信小程序接入
Android SDK接入
iOS SDK接入
移动浮层H5（移动端浏览器）

3.2 PaaS模式

PaaS模式提供纯API接口，开发者可以自行构建核身流程和UI界面。支持的API接口包括照片人脸核身、活体人脸比对、身份信息认证等。

4. SaaS化服务接入完整流程

SaaS化服务是人脸核身最常用的接入方式。以下以微信浮层H5为例，详细说明完整的接入流程。

4.1 步骤一：创建RuleId（业务流程）

RuleId是SaaS化服务调用的核心标识，用于配置和管理核身业务流程。创建步骤如下：

登录腾讯云人脸核身控制台，在自主接入页面，单击创建业务流程。
选择应用场景（如微信H5浮层/普通模式），选择应用类型（Plus版/增强版/基础版）。
进入接入配置，填写页面标题、业务名称、业务描述等信息。
选择人脸比对库源：跟权威库比对（收费较高）或跟上传照片比对（自传照片）。
配置身份证OCR功能、活体检测方式、意愿确认流程等。
确认配置信息后提交审核。

审核通过后即可获得RuleId，用于后续的API调用。

4.2 步骤二：获取BizToken

每次调用人脸核身SaaS化服务前，需要先调用实名核身鉴权（DetectAuth）接口获取BizToken。BizToken用来串联核身流程，在验证完成后用于获取验证结果信息。

DetectAuth接口的核心输入参数如下：

RuleId（必填）：在控制台创建的业务流程ID
Name（可选）：验证人的姓名，是否必传取决于控制台配置
IdCard（可选）：验证人的身份证号码，是否必传取决于控制台配置
RedirectUrl（可选）：认证结束后重定向的回调链接地址，仅微信H5场景使用
Extra（可选）：透传字段，在获取验证结果时返回

接口请求域名为 faceid.tencentcloudapi.com，默认接口请求频率限制为100次/秒。

调用DetectAuth接口成功后，会返回BizToken和用于发起核身流程的URL。BizToken具有以下重要特性：

有效时间为7200秒（2小时）
仅能用于一次核身流程
完成认证后，三天内可用BizToken多次获取验证结果信息

4.3 步骤三：跳转核身URL完成验证

获取BizToken后，将用户引导至返回的核身URL。用户在该页面上完成证件拍摄、活体检测、人脸比对等核身流程。如果输入参数RedirectUrl为空，则用户完成核验后默认跳转腾讯云人脸核身产品介绍页。

4.4 步骤四：获取核身结果

用户完成验证后，开发者调用获取实名核身结果信息（GetDetectInfoEnhanced）接口，传入BizToken获取验证结果。结果信息包括文本信息、识别分数、照片和视频等。注意结果信息仅在慧眼侧保留3天，请及时拉取。

判断核验是否通过的标准是：调用GetDetectInfoEnhanced接口后，Response.Text.ErrCode == 0 为true，则认为整个核验流程通过。

5. 各端SDK接入详解

5.1 微信小程序接入

微信小程序接入流程如下：

登录人脸核身控制台，单击自助接入，创建业务流程，获取RuleId和小程序SDK下载链接。
下载小程序SDK，在小程序代码中引入并调用init方法进行初始化。
小程序开发需要授权，小程序管理员扫码后，只勾选人脸核身权限授权给慧眼第三方平台。
在小程序开发管理的接口设置中开启实时播放音视频流和实时录制音视频流功能。
将相关域名添加至服务器域名白名单。

5.2 Android端SDK集成

Android端慧眼SDK适用于API 21（Android 5.0）及以上的版本。

添加依赖：

将SDK的aar文件添加到工程module的libs目录下：

dependencies {
    implementation files("libs/HuiYanPublicEnhancedSDK-release-4.x.x.aar")
    implementation files("libs/HuiYan-Secret4lib-1.0.1-release.aar")
    implementation files("libs/tencent-ai-sdk-aicamera-2.0.1-release.aar")
    implementation files("libs/tencent-ai-sdk-common-2.0.1.1-release.aar")
    implementation files("libs/tencent-ai-sdk-network-2.0.1.3-release.aar")
    implementation files("libs/tencent-ai-sdk-youtu-base-1.0.1.44-release.aar")
    implementation files("libs/huiyanmodels_1.0.2_release.aar")
}

添加授权文件：

将申请到的YTFaceSDK.license文件放到assets目录下。

权限声明：

在AndroidManifest.xml中添加摄像头权限：

<uses-permission android:name="android.permission.CAMERA" />

SDK初始化与调用：

SDK代码调用的入口为WbCloudFaceVerifySdk类：

// 获取单例对象
WbCloudFaceVerifySdk sdk = WbCloudFaceVerifySdk.getInstance();

// 准备输入数据
WbCloudFaceVerifySdk.InputData inputData = new WbCloudFaceVerifySdk.InputData(
    faceId,        // 刷脸ID
    agreementNo,   // 订单号
    openApiAppId,  // WBappid
    openApiAppVersion, // 版本号
    openApiNonce,  // 32位随机字符串
    openApiUserId, // 用户ID
    openApiSign,   // 签名
    verifyMode,    // 刷脸类型
    keyLicence     // SDK license
);

// 初始化SDK
sdk.initPlusSdk(context, data, new WbCloudFaceVerifyLoginListener() {
    @Override
    public void onLoginSuccess() {
        // 登录成功，拉起刷脸页面
        sdk.startWbFaceVerifySdk(context, new WbCloudFaceVerifyResultListener() {
            @Override
            public void onResult(int statusCode, String statusMsg, String result) {
                // 处理刷脸结果
                sdk.release(); // 释放资源
            }
        });
    }
    
    @Override
    public void onLoginFailed(int errorCode, String errorMsg) {
        // 处理登录失败
    }
});

InputData对象中各参数的详细说明如下：

faceId：刷脸ID号，必填
agreementNo：订单号，合作方订单的唯一标识，长度32字节，必填
openApiAppId：业务流程唯一标识即WBappid，长度8字节，必填
openApiAppVersion：接口版本号，默认填1.0.0，长度20字节，必填
openApiNonce：32位随机字符串，每次请求需要的一次性nonce，必填
openApiUserId：用户ID，每个用户唯一的标识，长度32字节，必填
openApiSign：签名，长度40字节，必填
verifyMode：刷脸类型（分级模式等），必填
keyLicence：在控制台申请的SDK license，必填

注意NONCE类型的ticket有效期为120秒，且一次性有效，每次启动SDK刷脸都要重新请求NONCE ticket并重新计算签名。

5.3 iOS端SDK集成

iOS端慧眼SDK适用于iOS 9.0及以上版本，开发环境需要Xcode 11.0或以上。

手动接入：

导入相关Framework，在Link Binary With Libraries中导入HuiYanPublicSDK.framework。在Copy Bundle Resources中导入face-tracker-v003.bundle、HuiYanSDKUI.bundle等资源文件。

CocoaPods接入：

创建CloudHuiYanSDK_FW目录，将SDK包放入Frameworks和Resources子目录中。创建podspec文件并配置相关参数。在Podfile中添加依赖并执行pod install。

权限设置：

在Info.plist中添加摄像头权限声明：

<key>Privacy - Camera Usage Description</key>
<string>人脸核身需要开启您的摄像头权限，用于识别</string>

6. API接口调用详解（PaaS模式）

对于需要完全自定义核身流程的场景，可以使用PaaS模式的API接口。所有API接口的请求域名为 faceid.tencentcloudapi.com。

6.1 照片人脸核身

照片人脸核身接口（ImageRecognitionV2）传入照片和身份信息，判断该照片与权威库的证件照是否属于同一个人。默认接口请求频率限制为20次/秒。

核心输入参数：

IdCard（必填）：身份证号
Name（必填）：姓名，中文请使用UTF-8编码
ImageBase64（必填）：用于人脸比对的照片的Base64值，图片大小不超过3M，仅支持jpg、png格式

输出参数包括相似度（Sim，取值范围0.00-100.00）。推荐相似度大于等于70时可判断为同一人，阈值70的误通过率为万分之一。

6.2 活体人脸比对

活体人脸比对接口（LivenessCompare）传入视频和照片，先判断视频中是否为真人，判断为真人后，再判断该视频中的人与上传照片是否属于同一个人。默认接口请求频率限制为100次/秒。

6.3 API调用代码示例（Python）

以下示例演示如何使用Python SDK调用DetectAuth接口获取BizToken：

import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.faceid.v20180301 import faceid_client, models

def get_biz_token(secret_id, secret_key, rule_id, name, id_card, redirect_url):
    cred = credential.Credential(secret_id, secret_key)
    httpProfile = HttpProfile()
    httpProfile.endpoint = "faceid.tencentcloudapi.com"
    clientProfile = ClientProfile()
    clientProfile.httpProfile = httpProfile
    client = faceid_client.FaceidClient(cred, "", clientProfile)
    req = models.DetectAuthRequest()
    params = {
        "RuleId": rule_id,
        "Name": name,
        "IdCard": id_card,
        "RedirectUrl": redirect_url
    }
    req.from_json_string(json.dumps(params))
    resp = client.DetectAuth(req)
    return resp.BizToken, resp.Url

# 调用示例
secret_id = "您的SecretId"
secret_key = "您的SecretKey"
rule_id = "您的RuleId"
biz_token, auth_url = get_biz_token(
    secret_id, secret_key, rule_id,
    "张三", "110101199001011234",
    "https://your-domain.com/callback"
)
print(f"BizToken: {biz_token}")
print(f"核身URL: {auth_url}")

以下示例演示如何获取核身结果：

def get_detect_info(secret_id, secret_key, biz_token):
    cred = credential.Credential(secret_id, secret_key)
    httpProfile = HttpProfile()
    httpProfile.endpoint = "faceid.tencentcloudapi.com"
    clientProfile = ClientProfile()
    clientProfile.httpProfile = httpProfile
    client = faceid_client.FaceidClient(cred, "", clientProfile)
    req = models.GetDetectInfoEnhancedRequest()
    params = {
        "BizToken": biz_token
    }
    req.from_json_string(json.dumps(params))
    resp = client.GetDetectInfoEnhanced(req)
    return resp

# 调用示例
result = get_detect_info(secret_id, secret_key, biz_token)
# 判断核验是否通过
if result.Text.ErrCode == "0":
    print("核验通过")
else:
    print(f"核验失败: {result.Text.ErrMsg}")

7. 最佳实践与注意事项

7.1 BizToken管理

BizToken有效时间为7200秒，且仅能使用一次。建议在用户准备开始核身前才调用DetectAuth接口获取BizToken，避免过早获取导致过期。完成认证后，应在三天内调用GetDetectInfoEnhanced接口拉取结果信息。

7.2 接口调用安全

DetectAuth接口建议由客户业务后端调用，而非前端直接调用。将SecretId和SecretKey保存在服务端，避免泄露。API调用时需要进行签名认证，具体签名方法请参考腾讯云API公共参数文档。

7.3 限频策略

不同接口有不同的频率限制。DetectAuth接口限制为100次/秒，照片人脸核身接口限制为20次/秒。此外，同一个腾讯云AppId下，同一个姓名每天核验次数不得超过500次，触发限频策略将会返回相应错误码。

7.4 错误码处理

调用API时可能遇到各类错误码，常见的有：

AuthFailure.InvalidAuthorization：请求头部的Authorization不符合腾讯云标准
AuthFailure.SecretIdNotFound：密钥不存在，请检查控制台密钥是否被删除或禁用
FailedOperation相关错误码：业务逻辑错误，如人脸验证失败等

7.5 结果信息拉取

慧眼侧的结果信息仅保留3天，请及时拉取。如果在未完成验证前调用GetDetectInfoEnhanced接口，数据可能为null。建议在用户完成核身后通过回调或轮询方式主动拉取结果。

7.6 回调地址配置

在DetectAuth接口中传入正确的RedirectUrl（需要是http://或https://开头），慧眼会在用户验证完成后跳转相应的Url。如果未配置回调地址，完成验证后会默认跳转到腾讯网。

7.7 安全增强建议

对于高安全要求的场景，建议使用Plus版人脸核身，其多模态大模型和黑产模板批量识别能力能够有效防御AIGC合成攻击和模板注入攻击。同时，增强版提供的设备风险检测功能能够根据风险等级智能选择认证方式。

8. 常见问题解答

问题1：人脸核身服务申请需要多长时间？

答：开通人脸核身服务本身较快，企业实名认证通过后即可提交申请。但如果需要通过微信小程序或微信原生H5接入，还需要额外的资质审核，需要5到7个工作日。建议提前预留好上线时间。

问题2：BizToken过期了怎么办？

答：BizToken有效时间为7200秒（2小时）。如果过期，需要重新调用DetectAuth接口获取新的BizToken。建议在用户准备开始核身前才调用获取接口，避免过早获取导致过期。

问题3：如何判断人脸核身是否通过？

答：调用GetDetectInfoEnhanced接口后，判断Response.Text.ErrCode == 0是否为true。如果为true，则整个核验流程通过。注意不要仅判断单个环节的状态码，因为活体检测环节允许重试。

问题4：人脸核身支持哪些接入渠道？

答：SaaS模式支持微信HTML5接入、微信小程序、Android SDK、iOS SDK等接入方式。PaaS模式支持API接入。具体选择哪种方式取决于业务场景和技术栈。

问题5：人脸核身的计费方式是怎样的？

答：人脸核身默认是按量计费模式（后付费），也可以购买资源包（预付费）。购买资源包后会优先抵扣资源包，资源包抵扣完后自动转为按量计费。不同产品版本和接入渠道的单价不同，例如增强版人脸核身（权威库）-APP约为0.3元/次。不论SaaS还是PaaS模式，都是按照有效的调用次数计费。

问题6：人脸核身结果信息保存多久？

答：结果信息在慧眼侧仅保留3天。建议在用户完成验证后尽快调用GetDetectInfoEnhanced接口拉取结果信息，包括文本信息、识别分数、照片和视频等。如需长期保存，请自行存储。