腾讯云人脸核身对接使用完全指南：从开通到上线

1. 腾讯云人脸核身：产品体系与选型指南

腾讯云慧眼人脸核身是一组对用户身份信息真实性进行验证审核的服务套件，提供人脸核身、身份信息核验、银行卡要素核验和运营商类要素核验等各类实名信息认证能力。目前腾讯云慧眼人脸核身服务分为Plus版人脸核身、增强版人脸核身、基础版人脸核身、意愿核身、实名信息核验、E证通、实证NFC和AI人脸防护盾八大子产品。对于大多数需要远程核验身份的场景，开发者主要关注的是基础版、增强版和Plus版这三个人脸核身产品。

基础版人脸核身服务是一套集成了证件OCR识别、活体检测和人脸比对三大功能的身份信息验证业务流程。验证通过率高、稳定性强，秒级确认用户身份，适用于金融、保险、共享出行等远程实名或在线核验身份的场景。增强版人脸核身服务在基础版的基础上，通过设备安全增强、活体安全增强、智能分级认证增强，全面升级核身安全能力。它能够在刷脸核身的同时实时检测当前设备的风险，根据风险等级智能选择认证方式，有效拦截多种类型的刷脸攻击，针对摄像头劫持、恶意注入等攻击方式拦截准确率可达到99.9%。Plus版人脸核身在增强版的基础上更进一步，新增多模态大模型、黑产模板批量识别、模型自学习、智能审核等更多高级安全功能，能够有效拦截传统活体检测模型无法识别的AIGC合成攻击以及黑产批量的模板注入攻击。

在选型建议上，如果业务场景对安全要求一般、预算有限，基础版即可满足；如果涉及金融交易、密码修改等高安全等级场景，建议选择增强版；如果面临黑产攻击风险较高或需要最前沿的防御能力，Plus版是最佳选择。此外，意愿核身产品结合增强版人脸核身与语音AI能力，用户通过拍摄人脸视频并进行语音朗读或回答即可完成实名、实人、真意愿的校验，适用于需要确认用户真实意愿的合规场景。

2. 接入前置条件：账号、资质与权限准备

在开始技术对接之前，需要完成一系列前置准备工作。

第一步：注册腾讯云账号并完成企业实名认证。申请开通人脸核身服务需要腾讯云账号为企业实名用户。注册腾讯云账号后，进入人脸核身控制台即可开通相应服务。前往人脸核身产品介绍页，单击申请免费试用，按需求正确填写具体业务信息后提交申请，即可开通腾讯云慧眼人脸核身服务。

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

第二步：了解行业资质要求。如需使用微信小程序或微信原生H5的人脸核身产品，需符合特定行业要求且具备相关资质。支持的行业类目包括政务（机构或事业单位）、金融（银行、保险、信托、基金、证券/期货、持牌消费金融）、医疗（公立医疗机构、互联网医院、三级私立医院）、运营商（基础电信运营商、增值电信运营商）、教育（学历教育）、出行与交通（网约车、航空、地铁等）、生活服务、旅游、商业服务（公证）、社交（直播）、快递与邮政等。接入前请登录微信公众平台，打开设置>基本设置>服务类目，确认小程序服务类目满足要求，并准备好对应的资质文件，资质审核需要5至7个工作日，请预留好上线时间。

第三步：小程序授权与域名白名单配置。小程序开发需要授权，打开授权二维码，小程序管理员扫码后单击授权项，只勾选人脸核身权限，将该权限授权给慧眼第三方平台。小程序前端接口请求有域名白名单限制，未添加白名单的域名只能在调试模式下运行。接入方需要在小程序上线前将以下域名添加至服务器域名白名单：https://events.tim.qq.com、https://faceid.qq.com、https://grouptalk等。

3. 控制台配置：创建业务流程获取RuleId

完成前置准备后，进入人脸核身控制台进行业务流程配置，获取RuleId。

登录腾讯云人脸核身控制台，在自主接入页面，单击创建业务流程。根据业务场景选择应用场景，可选场景包括微信H5（浮层/普通模式）、微信小程序、Plus版App SDK等。应用类型可选择Plus版人脸核身、增强版人脸核身或基础版人脸核身。若需同时在微信场景及非微信场景使用，或需要在微信鸿蒙NEXT场景使用，将是否需要在微信外打开选择为是。

进入接入配置后，根据业务实际场景填写页面标题、业务名称、业务描述等信息。选择人脸比对库源，支持两种方式：跟权威库比对和跟上传照片比对。跟权威库比对是将用户人脸与权威库（如公安库）的证件照进行比对；跟上传照片比对是将用户人脸与业务方自行上传的照片进行比对。配置身份证OCR功能，如果不需要则勾选不需要用户在验证时上传。配置活体检测方式，微信浮层H5支持一闪活体检测（眨眼加光线）和随机双动作检测。配置意愿页面，根据业务情况勾选是否增加用户意愿确认流程。配置结果页的文案描述。业务信息填写完成后，确认配置信息后单击确认并提交审核。审核通过后即可获得RuleId，RuleId用于调用配置的业务流程。

4. 服务端API调用：获取BizToken

完成RuleId创建后，服务端需要调用实名核身鉴权接口（DetectAuth）获取BizToken。BizToken是仅一次核身流程的标识，有效时间为7,200秒；用户完成核身后，开发者可用该标识获取验证结果信息，结果信息仅保留3天。

接口请求域名为faceid.tencentcloudapi.com。默认接口请求频率限制为100次/秒。推荐使用API Explorer进行在线调试，API Explorer提供了在线调用、签名验证、SDK代码生成和快速检索接口等能力。

以下是Java语言调用DetectAuth接口获取BizToken的示例代码：

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.faceid.v20180301.FaceidClient;
import com.tencentcloudapi.faceid.v20180301.models.DetectAuthRequest;
import com.tencentcloudapi.faceid.v20180301.models.DetectAuthResponse;

public class DetectAuthDemo {
    public static void main(String[] args) {
        try {
            // 实例化认证对象，入参需要传入腾讯云账户SecretId和SecretKey
            Credential cred = new Credential("您的SecretId", "您的SecretKey");
            
            // 实例化http配置
            HttpProfile httpProfile = new HttpProfile();
            httpProfile.setEndpoint("faceid.tencentcloudapi.com");
            
            // 实例化client配置
            ClientProfile clientProfile = new ClientProfile();
            clientProfile.setHttpProfile(httpProfile);
            
            // 实例化人脸核身client对象
            FaceidClient client = new FaceidClient(cred, "", clientProfile);
            
            // 实例化请求对象
            DetectAuthRequest req = new DetectAuthRequest();
            req.setRuleId("您的RuleId");
            req.setName("张三");
            req.setIdCard("110101199003071234");
            req.setRedirectUrl("https://您的回调地址.com/callback");
            
            // 发起请求并获取响应
            DetectAuthResponse resp = client.DetectAuth(req);
            
            // 输出BizToken
            System.out.println("BizToken: " + resp.getBizToken());
            System.out.println("RequestId: " + resp.getRequestId());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

以下是Python语言调用DetectAuth接口的示例代码：

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):
    try:
        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()
        req.RuleId = rule_id
        req.Name = name
        req.IdCard = id_card
        req.RedirectUrl = redirect_url
        resp = client.DetectAuth(req)
        return resp.BizToken
    except Exception as e:
        print(e)
        return None

if __name__ == "__main__":
    SECRET_ID = "您的SecretId"
    SECRET_KEY = "您的SecretKey"
    RULE_ID = "您的RuleId"
    result = get_biz_token(SECRET_ID, SECRET_KEY, RULE_ID, "张三", "110101199003071234", "https://您的回调地址.com/callback")
    print("BizToken:", result)

DetectAuth接口的核心输入参数包括：RuleId（业务流程ID，必填）、Name（验证人姓名，最长32位，中文请使用UTF-8编码）、IdCard（验证人身份证号码）、RedirectUrl（认证结束后重定向的回调链接地址，仅微信H5场景使用，最长1024位）。Extra参数为透传字段，在获取验证结果时返回，最长1024位。ImageBase64参数用于人脸比对的图像数据，使用Base64编码，图片大小不超过3M，仅支持jpg、png格式。

5. 前端SDK集成：小程序、H5与App

腾讯云人脸核身支持多渠道接入。SaaS模式支持微信HTML5接入、微信小程序、Android SDK、iOS SDK等接入。PaaS模式支持API接入。不同接入方式对应的活体检测模式有所不同。

5.1 微信小程序接入

微信小程序接入流程如下：登录人脸核身控制台，单击自助接入>创建业务流程，完成微信H5/小程序服务的业务流程创建，获取RuleID和小程序SDK下载链接。下载小程序SDK并在小程序代码中引入，调用init方法进行初始化。接入方服务端调用DetectAuth接口获取BizToken。客户后端将BizToken返回给客户小程序端，小程序调用核身方法startVerify进入核身流程。用户完成人脸核身后以回调函数形式返回BizToken，接入方小程序将BizToken传给接入方服务端，服务端凭BizToken调用GetDetectInfoEnhanced接口获取本次核身的详细信息。

小程序SDK安装步骤如下：将小程序SDK文件夹放在小程序根目录下，使用require函数引入：const Verify = require('/verify_mpsdk/main')。请在微信开发者工具中使用手机预览模式进行调试，请勿使用真机调试。卸载时删除verify_mpsdk文件夹，移除相应require代码即可。小程序接入有行业类目限制，审核时间3至5天。

5.2 H5接入

H5接入主要分为微信浮层H5（微信浏览器）和微信原生H5（微信公众号）两种方式。浮层H5能够兼容大部分用户的微信浏览器环境，仅有少部分浏览器不支持（低于5%），当检测到浏览器不兼容时会自动切换为普通H5模式。微信浮层H5对iOS系统版本要求14.3以上、微信版本6.5以上，Android端都支持。

H5接入的活体检测模式支持一闪活体检测（眨眼加光线）和随机双动作检测。调用DetectAuth接口获取BizToken后，前端跳转到返回的核身URL即可开始核身流程。用户完成核身后会重定向到指定的RedirectUrl。

5.3 App SDK接入（Android示例）

Android版慧眼公有云（增强版）SDK适用于API 21（Android 5.0）及以上的版本。集成步骤如下：

将HuiyanPublicEnhancedSDK-release-4.x.x.x.aar及其他基础组件库添加到工程module下的libs目录。SDK提供的组件库包括：HuiyanPublicEnhancedSDK（核心SDK）、HuiYan-Secret4lib（国密库）、tencent-ai-sdk-aicamera（相机组件）、tencent-ai-sdk-common（公共组件）、tencent-ai-sdk-network（网络组件）、tencent-ai-sdk-youtu-base（优图基础库）、huiyanmodels（模型库）等。YTFaceSDK.license文件需要主动申请，联系客服人员进行license申请后将license文件放到assets目录。

在build.gradle中添加依赖：

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")
}

在AndroidManifest.xml中声明摄像头权限：<uses-permission android:name="android.permission.CAMERA" />。对于Android 6.0以上用户，除在AndroidManifest.xml中声明外，还需使用代码动态申请权限。

SDK代码调用的入口为WbCloudFaceVerifySdk类。先通过getInstance()获得单例对象，调用initSdk方法初始化，传入包含faceId、agreementNo、openApiAppId、openApiNonce、openApiUserId、openApiSign等参数的Bundle数据。登录成功后调用startWbFaceVerifySdk拉起SDK页面。收到刷脸结果后调用release方法释放资源。NONCE类型的ticket有效期为120秒且一次性有效，每次启动SDK刷脸都要重新请求NONCE ticket并重新计算sign。

6. 获取核身结果：GetDetectInfoEnhanced接口

用户完成人脸核身后，服务端需要调用获取实名核身结果信息增强版接口（GetDetectInfoEnhanced）获取核身详细信息。该接口使用SdkToken（即BizToken）作为参数，BizToken生成后两小时内可多次拉取结果。

以下是Java调用GetDetectInfoEnhanced接口的示例：

import com.tencentcloudapi.faceid.v20180301.FaceidClient;
import com.tencentcloudapi.faceid.v20180301.models.GetDetectInfoEnhancedRequest;
import com.tencentcloudapi.faceid.v20180301.models.GetDetectInfoEnhancedResponse;

public class GetDetectInfoDemo {
    public static void main(String[] args) {
        try {
            Credential cred = new Credential("您的SecretId", "您的SecretKey");
            HttpProfile httpProfile = new HttpProfile();
            httpProfile.setEndpoint("faceid.tencentcloudapi.com");
            ClientProfile clientProfile = new ClientProfile();
            clientProfile.setHttpProfile(httpProfile);
            FaceidClient client = new FaceidClient(cred, "", clientProfile);
            
            GetDetectInfoEnhancedRequest req = new GetDetectInfoEnhancedRequest();
            req.setBizToken("从核身回调中获取的BizToken");
            
            GetDetectInfoEnhancedResponse resp = client.GetDetectInfoEnhanced(req);
            System.out.println("核身结果: " + resp.getDetectInfo());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

核身结果信息中包含了本次核身的详细数据，包括验证是否通过、活体检测分数、人脸比对分数、用户身份信息等。开发者可根据返回结果中的验证状态字段判断核身是否成功，并据此执行业务逻辑（如放行用户、完成注册等）。

7. 安全机制：签名与鉴权

腾讯云人脸核身API采用签名机制保证请求的合法性和安全性。每次请求均需要携带签名参数（Signature），用来验证此次请求的合法性，用户需要根据实际的输入参数计算得出。公共参数是用于标识用户和接口签名的参数，每次请求均需要携带这些参数才能正常发起请求。

签名计算的具体方法参考腾讯云API文档。开发者可以使用腾讯云提供的SDK，SDK会自动处理签名计算，无需手动实现。如果使用API Explorer，可自动生成包含签名的调用示例。

在App SDK集成中，NONCE类型的ticket有效期为120秒且一次性有效，每次启动SDK刷脸都要重新请求NONCE ticket并重新计算sign。建议合作方做前端保护，防止用户连续点击导致短时间内频繁启动SDK。

8. 计费模式与成本优化

腾讯云人脸核身提供预付费和后付费两种计费方式。默认是按量计费模式（后付费），无法直接更改为预付费。如需预付费可以购买资源包，购买资源包后会优先抵扣资源包，资源包抵扣完后转为按量计费。资源包有效期均为1年，过期作废，支持7天内无理由退款。1年内若资源包次数未使用完则过期作废。

活体人脸核身包括身份信息核验的费用。人脸核身不同版本和不同接入方式的计费价格不同。跟权威库比对和跟上传照片比对的收费价格不同。OCR不再单独收费。Plus版人脸核身如配置了增加意愿确认流程，则将按意愿核身价格计费。

成本优化建议：根据业务量合理选择资源包规格；关注每月免费调用额度（如有）；合理规划接入方式，不同接入方式可能有不同的计费标准；监控调用量防止超额。

9. 常见问题与排障

问题1：调用DetectAuth接口返回错误怎么办？首先检查SecretId和SecretKey是否正确，RuleId是否已审核通过，Name和IdCard是否按照UTF-8编码传入。可以使用API Explorer在线调试，快速定位问题。

问题2：小程序接入时提示类目不符合要求？登录微信公众平台检查小程序的服务类目是否在支持的范围内。如果不支持，需先变更小程序类目或选择其他接入方式（如H5或App SDK）。

问题3：BizToken的有效期是多久？BizToken有效时间为7,200秒（2小时），用户完成核身后结果信息仅保留3天。获取核身结果应在有效期内进行。

问题4：NONCE ticket和BizToken有什么区别？NONCE ticket用于App SDK的签名计算，有效期为120秒且一次性有效。BizToken是核身流程的标识，有效期为7,200秒，用于串联整个核身流程和获取结果。

问题5：人脸核身支持哪些活体检测模式？支持多种活体检测模式，包括一闪活体检测（眨眼加光线）、随机双动作检测、数字模式（用户准确念出下发的四位验证码）、动作模式、静默模式等。不同接入方式支持的活体检测模式有所不同。

问题6：如何获取腾讯云API密钥？登录腾讯云控制台，进入访问管理>API密钥管理，即可创建和查看SecretId和SecretKey。请妥善保管密钥，避免泄露。