tencent cloud

人脸核身

动态与公告
产品动态
产品公告
产品简介
产品概述
产品优势
应用场景
购买指南
计费概述
购买方式
欠费说明
退费说明
接入文档
开始集成
活体人脸比对(纯 API)接入指引
活体人脸比对 (移动端H5) 接入指引
活体人脸比对 (App SDK) 接入指引
卡证活体人脸比对(移动端 H5)接入指引
卡证活体人脸比对(App SDK)接入指引
其他指引
API 文档
History
Introduction
API Category
Making API Requests
Selfie Verification (Pure API) APIs
Selfie Verification (App SDK) APIs
Identity Verification (App SDK) APIs
Identity Verification(Mobile HTML5) APIs
AI Face Shield (Pure API) APIs
Other APIs
Data Types
Error Codes
常见问题
联系我们
词汇表
eKYC 政策
隐私协议
数据处理和安全协议
服务等级协议

接入流程说明

PDF
聚焦模式
字号
最后更新时间: 2026-02-11 16:06:43

接入准备

注册腾讯云企业账号,请见 注册指引
完成企业实名认证,请见 企业实名指引
登录慧眼控制台 开通服务
联系我们 获取最新的 SDK 及 License。

整体架构图

下图为活体人脸比对 SDK 集成的架构图:

image.5


慧眼 SDK 集成包括两部分:
客户端集成: 将慧眼 SDK 集成到客户终端业务 App 中。
服务器端集成: 在您的(商家)服务器中公开您的(商家)应用程序的端点,以便商家应用程序可以与商家服务器交互,然后访问 FaceId SaaS API 以获取串联活体比对流程的SdkToken以及通过SdkToken拉取最终的核身结果。

整体交互流程

集成方只需要传入 Token 并启动对应的慧眼 SDK 的活体检测方法,便可以完成活体检测,并返回活体结果。
1. Token 的获取可以参考云 API 接口:GetFaceldTokenIntl
2. 用户主动拉取活体结果的云 API 接口:GetFaceIdResultIntl
下图展示了 SDK 客户端以及服务器端的整体交互逻辑,图中各负责模块解析:



具体的推荐交互流程如下:
1. 用户触发终端 Merchant Application 准备调用核身业务场景。
2. Merchant Application 发送请求到 Merchant Server,告知启动一次核身业务需要活体业务 Token。
3. Merchant Server 传入相关参数调用云 API 接口 GetFaceldTokenIntl
4. FaceID SaaS 接收到 GetFaceldTokenIntl 调用后,下发此次业务的 token 给 Merchant Server。
5. Merchant Server 可以将获取到的业务 Token ,下发给客户的 Merchant Application 。
6. Merchant Application 调用慧眼 SDK 的启动接口 startHuiYanAuth 传入 token 与配置信息,开始核身验证。
7. FaceID SDK 捕捉并上传所需的用户数据,包括活体数据等,上传至 FaceID SaaS 。
8. FaceID SaaS 在完成核身检测(包括活体与比对流程)以后,会返回结果给 FaceID SDK 。
9. FaceID SDK 主动触发回调给 Merchant Application 通知核验完成以及核验状态。
10. Merchant Application 接收到回调以后,可以发送请求通知 Merchant Server 去主动获取本次核身的结果,进行确认检查。
11. Merchant Server 主动调用 FaceID SaaS 的接口 GetFaceIdResultIntl 传入相关参数以及本次业务的 Token ,去获取本次核身的结果。
12. FaceID SaaS 接收到 GetFaceIdResultIntl 调用后,会返回本次核身的结果到 Merchant Server。
13. Merchant Server 接收到本次核身的结果后,可以下发需要的信息到 Merchant Application。
14. Merchant Application 展示最后的结果,呈现在 UI 界面上,告知用户核身的结果。

接入流程

服务器端集成

1. 集成准备

在服务端集成之前,你需要按照 获取 API 密钥指引 中的说明进行操作,开通腾讯云慧眼服务,并且拿到了腾讯云API 访问密钥 SecretId 和 SecretKey 。除此之外你还需要按照 连接腾讯云 API 接口 中的操作流程,引入你所熟悉开发语言的 SDK 包到你服务端模块中,以确保可以成功调用腾讯云 API 以及正确处理 API 请求和响应。

2. 开始集成

为了确保你的(商户)客户端应用程序能够跟你的(商户)服务端正常交互,商户服务端需要调用慧眼提供的 API 接口 GetFaceIdTokenIntl 获取 SDKToken 串联整个活体比对流程以及调用 GetFaceIdResultIntl 接口获取活体比对结果,商户服务端需要提供相应的端点给商户客户端调用,下面的示例代码使用 Golang 语言作为案例,展示如何在服务端调用腾讯云 API 接口并拿到正确的响应结果。
注意:
该示例中仅仅演示商户服务端与腾讯云 API 服务交互所需要的处理逻辑,如果有需要的话你需要自己实现你的业务逻辑,比如:
当你通过 GetFaceIdTokenIntl 接口获取活体比对 SDKToken 之后,可以将客户端应用程序需要的其他响应同 SDKToken 一并返回给客户端。
当你通过 GetFaceIdResultIntl 接口获取活体比对结果之后,可以将返回的最佳帧照片保存起来,以便后续业务逻辑使用。
var FaceIdClient *faceid.Client

func init() {
// 初始化客户端配置对下,您可以指定超时时间和其他配置项
prof := profile.NewClientProfile()
prof.HttpProfile.ReqTimeout = 60
// TODO 需要替换成您调用账号的 SecretId 和 SecretKey
credential := cloud.NewCredential("SecretId", "SecretKey")
var err error
// 初始化调用慧眼人脸核身服务的客户端
FaceIdClient, err = faceid.NewClient(credential, "ap-singapore", prof)
if nil != err {
log.Fatal("FaceIdClient init error: ", err)
}
}

// GetFaceIdToken 获取人脸核身Token
func GetFaceIdToken(w http.ResponseWriter, r *http.Request) {
log.Println("get face id token")
// 步骤1: 解析请求参数
_ = r.ParseForm()
var SecureLevel = r.FormValue("SecureLevel")

// 步骤2: 初始化请求对象,并给必要的参数赋值
request := faceid.NewGetFaceIdTokenIntlRequest()
request.SecureLevel = &SecureLevel
// 步骤3: 通过FaceIdClient调用人脸核身服务
response, err := FaceIdClient.GetFaceIdTokenIntl(request)

// 步骤4: 处理腾讯云API的响应,并构造返回对象
if nil != err {
_, _ = w.Write([]byte("error"))
return
}
SdkToken := response.Response.SdkToken
apiResp := struct {
SdkToken *string
}{SdkToken: SdkToken}
b, _ := json.Marshal(apiResp)

// ... 其他业务处理代码

//步骤5: 返回服务响应
_, _ = w.Write(b)
}

// GetFaceIdResult 获取人脸核身核验结果
func GetFaceIdResult(w http.ResponseWriter, r *http.Request) {
// 步骤1: ... 解析请求参数
_ = r.ParseForm()
SdkToken := r.FormValue("SdkToken")
// 步骤2: 初始化请求对象,并给必要的参数赋值
request := faceid.NewGetFaceIdResultIntlRequest()
request.SdkToken = &SdkToken
// 步骤3: 通过FaceIdClient调用人脸核身服务
response, err := FaceIdClient.GetFaceIdResultIntl(request)

// Step 4: 处理腾讯云API的响应,并构造返回对象
if nil != err {
_, _ = w.Write([]byte("error"))
return
}
result := response.Response.Result
apiResp := struct {
Result *string
}{Result: result}
b, _ := json.Marshal(apiResp)

// ... 其他业务处理代码

//步骤5: 返回服务响应
_, _ = w.Write(b)
}

func main() {
// 注册http接口路径
http.HandleFunc("/api/v1/get-token", GetFaceIdToken)
http.HandleFunc("/api/v1/get-result", GetFaceIdResult)
// 监听端口
err := http.ListenAndServe(":8080", nil)
if nil != err {
log.Fatal("ListenAndServe error: ", err)
}
}

3. 接口测试

当你完成了集成之后,可以通过 postman 或者 curl 命令来测试当前的集成是否正确,通过访问 http://ip:port/api/v1/get-token 接口查看是否正常返回 SdkToken , 访问 http://ip:port/api/v1/get-result 接口查看 Result 字段的响应是否为 0 以判断服务端集成是否成功,具体的响应结果详见 API 接口部分的介绍。

Android 端集成

1. 依赖环境

当前 Android 端慧眼 SDK 适用于 API 19 ( Android 4.4 ) 及以上版本。

2. SDK 接入步骤

1. huiyansdk_android_overseas_1.0.9.6_release.aar(具体版本号以官网下载为准)和 tencent-ai-sdk-youtu-base-1.0.1.39-release.aar tencent-ai-sdk-common-1.1.36-release.aartencent-ai-sdk-aicamera-1.0.22-release.aar (具体版本号以最终提供为准) 添加到您工程的 libs 目录下。
├── codedemo
│ ├── build.gradle
│ ├── libs
│ │ ├── huiyansdk_android_overseas_1.0.9.14_release.aar
│ │ ├── tencent-ai-sdk-aicamera-1.0.25-release.aar
│ │ ├── tencent-ai-sdk-common-1.1.43-release.aar
│ │ ├── tencent-ai-sdk-network-1.0.2.3.6-release.aar
│ │ └── tencent-ai-sdk-youtu-base-1.0.1.44-release.aar
│ ├── proguard-rules.pro
│ └── src
│ └── main
2. 在您工程的 build.gradle 中(App 下的 build.gradle 文件)进行如下配置:
// 设置ndk so架构过滤(以armeabi-v7a为例,如果设备支持 arm64-v8a 也可以加)

defaultConfig {
ndk {
abiFilters 'armeabi-v7a'
}
}
dependencies {
// 引入SDK
implementation files("libs/huiyansdk_android_overseas_1.0.9.5_release.aar")
// 通用算法SDK
implementation files("libs/tencent-ai-sdk-youtu-base-1.0.1.32-release.aar")
// 通用能力组件库
implementation files("libs/tencent-ai-sdk-common-1.1.27-release.aar")
implementation files("libs/tencent-ai-sdk-aicamera-1.0.18-release.aar")
implementation files("libs/tencent-ai-sdk-network-1.0.2.3.6-release.aar")

// SDK需要依赖的第三方库
// gson
implementation 'com.google.code.gson:gson:2.8.9'
}
3. 同时需要在 AndroidManifest.xml 文件中进行必要的权限声明
<!-- 摄像头权限 -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature
android:name="android.hardware.camera"
android:required="true" />

<!-- SDK需要的网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 设备风控需要依赖 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- SDK可选需要的权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
对于需要兼容 Android 6.0 以上的用户,以上权限除了需要在 AndroidManifest.xml 文件中声明权限以外,还需使用代码动态申请权限。

3. SDK 接口使用说明

初始化接口
在您 App 初始化的时候调用,推荐在 Application 中调用,主要是进行一些 SDK 的初始化操作。
@Override
public void onCreate() {
super.onCreate();
instance = this;
// SDK需要在Application初始化时进行初始化
HuiYanOsApi.init(getApp());
}
SDK 的主要流程
集成方只需要传入 Token 并启动对应的活体检测方法,便可以完成活体检测,并返回活体结果。
Token 的获取可以参考云 API 接口:GetFaceIdTokenIntl
活体完成拉取结果可以参考云 API 接口:GetFaceIdResultIntl
下图展示了 SDK 、客户端以及服务器端的在精简集成方式下整体交互逻辑:

启动精简活体核身
// HuiYanOs的相关参数
HuiYanOsConfig huiYanOsConfig = new HuiYanOsConfig();
// 此license文件存放在assets下
huiYanOsConfig.setAuthLicense("YTFaceSDK.license");
// 设备风控的license文件(使用设备风控模式的情况下需要),也要存放在assets下
huiYanOsConfig.setRiskLicense("turing.lic");
// 开启设备风控能力
huiYanOsConfig.setOpenCheckRiskMode(true);
if (compatCheckBox.isChecked()) {
huiYanOsConfig.setPageColorStyle(PageColorStyle.Dark);
}

// 启动核身方法,开始的活体,currentToken为后台下发数据
HuiYanOsApi.startHuiYanAuth(currentToken, huiYanOsConfig, new HuiYanOsAuthCallBack() {
@Override
public void onSuccess(HuiYanOsAuthResult authResult) {
//显示结果
runOnUiThread(new Runnable() {
@Override
public void run() {
Toast.makeText(SimplifyActivity.this, "活体通过!", Toast.LENGTH_SHORT).show();
}
});
}

@Override
public void onFail(int errorCode, String errorMsg, String token) {
String msg = "活体失败 " + "code: " + errorCode + " msg: " + errorMsg + " token: " + token;
Log.e(TAG, "onFail" + msg);
//显示结果
runOnUiThread(new Runnable() {
@Override
public void run() {
Toast.makeText(SimplifyActivity.this, msg, Toast.LENGTH_SHORT).show();
}
});
}
});
HuiYanOsAuthResult 为活体成功的返回结果。
注意:
当前的 " YTFaceSDK.license " 和 “ turing.lic “ 文件是需要您主动申请的,暂时您可以联系客服人员进行 license 申请。将申请完成后的 license 文件放到 assets 文件下。
├── codedemo
│ ├── build.gradle
│ ├── libs
│ ├── proguard-rules.pro
│ └── src
│ └── main
│ └── assets
│ ├── turing.lic
│ └── YTFaceSDK.license
SDK 资源释放
在您 APP 退出使用的时候,可以调用 SDK 资源释放接口。
@Override
protected void onDestroy() {
super.onDestroy();
// 退出时做资源释放
HuiYanOsApi.release();
}
混淆规则配置
如果您的应用开启了混淆功能,为确保 SDK 的正常使用,请把以下部分添加到您的混淆文件中。
#SDK的混淆包含
-keep class com.tencent.could.huiyansdk.** {*;}
-keep class com.tencent.could.aicamare.** {*;}
-keep class com.tencent.could.component.** {*;}
-keep class com.tencent.youtu.** {*;}
-keep class com.tenpay.utils.SMUtils {*;}
-keep class com.tencent.turingface.** {*;}
-keep class com.turingface.sdk.** {*;}
-keep class com.tencent.cloud.ai.network.** {*;}

iOS 端集成

1. 依赖环境

1. 开发环境 Xcode 11.0 或以上
2. 慧眼 iOS SDK 适用于手机 iOS9.0 及以上版本

2. SDK 接入步骤

手动接入方式
1. 导入相关库及文件。
Link Binary With Libraries 导入相关 Framework
2. SDK 依赖的库如下:
└──HuiYanOverseasSDK.xcframework
3. Copy Bundle Resources 中导入授权文件、模型资源文件。
├── YTFaceSDK.license
├── turing.license
└── face-tracker-v003.bundle
4. Copy Bundle Resources 导入资源文件。
└── HuiYanSDKUI.bundle
使用 Pod 方式接入
1. 在项目的根目录中创建 CloudHuiYanSDK_FW 文件夹,在子目录中创建 Frameworks 和 Resources 文件夹,并将 SDK 包移动到该目录。结构如下:
├──Your Project.xcodeproj
├──Podfile
├──CloudHuiYanSDK_FW
├───────CloudHuiYanSDK_FW.podspec
├───────Frameworks
├────────────HuiYanOverseasSDK.xcframework
├───────Resources
├────────────HuiYanSDKUI.bundle
└────────────face-tracker-v003.bundle
2. CloudHuiYanSDK_FW 目录下创建 podspec 文件:
Pod::Spec.new do |s|
s.name = "CloudHuiYanSDK_FW"
s.version = "1.0.0"
s.platform = :ios, "9.0"
s.summary = 'frameworks and bundle resources for youtu mobile hdr'
s.homepage = 'xx'
s.license = 'MIT'
s.source = {
:git => 'xx' ,:tag => "#{s.version}"
}
s.static_framework = true
s.compiler_flags = "-ObjC"
s.author = {'xx' => 'xx'}
s.pod_target_xcconfig = {'VALID_ARCHS' =>['arm64', 'x86_64']}
s.subspec 'Resources' do |framework|
framework.resource = 'Resources/*.bundle'
end
s.subspec 'Framework' do |framework|
framework.frameworks = 'Accelerate'
framework.vendored_frameworks = 'Frameworks/*.xcframework'
end
end
3. 在 Podfile 设置:
target 'HuiYanAuthDemo' do
use_frameworks!
pod 'CloudHuiYanSDK_FW', :path => './CloudHuiYanSDK_FW'
end
4. Check configuration:
Build Settings -> Framework Search Paths add $(inherited)
Build Settings -> Other Linker Flags add $(inherited)
5. pod install 更新。
权限设置
SDK 需要手机网络及摄像头使用权限,请添加对应的权限声明。在主项目 info.plist 配置中添加下面 key-value 值。
<key>Privacy - Camera Usage Description</key>
<string>人脸核身需要开启您的摄像头权限,用于人脸识别</string>

3. 1 SDK 接口使用说明

SDK 主要流程
集成方只需要传入 Token 并启动对应的活体检测方法,便可以完成活体检测,并返回活体结果。
Token 的获取可以参考云 API 接口:ApplyLivenessToken
拉取活体检测结果可以参考云 API 接口:GetFaceIdResultIntl
下图展示了 SDK 、客户端以及服务器端在精简集成方式下整体交互逻辑:

启动活体核身
#import <HuiYanOverseasSDK/HuiYanSDK.h>

//获取token
NSString *faceToken = self.tokenTextField.text;
//配置SDK
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];
//设置lic
config.authLicense = [[NSBundle mainBundle] pathForResource:@"YTFaceSDK.license" ofType:@""];
//准备阶段超时配置
config.prepareTimeoutMs = 20000;
//动作阶段超时配置
config.actionTimeoutMs = 20000;
// 删除本地活体视频
config.isDeleteVideoCache = YES;
// 设置UI相关回调
config.delegate = self;
//自定义多语言配置
config.languageType = EN;
// config.userLanguageFileName = @"ko";
// config.userLanguageBundleName = @"UseLanguageBundle";
config.iShowTipsPage = YES;

[[HuiYanOSKit sharedInstance] startHuiYaneKYC:faceToken withConfig:config witSuccCallback:^(HuiYanOsAuthResult * _Nonnull authResult, id _Nullable reserved) {
NSString *token = authResult.faceToken;
} withFailCallback:^(int errCode, NSString * _Nonnull errMsg, id _Nullable reserved) {
NSString *showMsg = [NSString stringWithFormat:@"err:%d:%@",errCode,errMsg];
NSLog(@"err:%@",showMsg);
}];
注意:
当前的 “ YTFaceSDK.license ”文件需要您主动申请,暂时您可以联系客服人员进行 license 申请。将申请完成后的 license 文件放置到当前项目目录下,添加至资源文件 ( copy Bundle Resources ) 中。
启动增强模式/ Plus 模式
活体人脸比对提供增强模式( Enhance Mode )和 Plus 模式两种高级安全级别,通过结合设备风控技术进一步提升活体检测的安全性。启用这两种模式需要在 SDK 配置和 Token 获取两个环节进行相应设置。
1. SDK 配置要求
无论启用增强模式还是 Plus 模式,都需要在 SDK 中开启设备风控能力并配置相应的风控 license 文件:
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];
config.authLicense = [[NSBundle mainBundle] pathForResource:@"YTFaceSDK.license" ofType:@""];
config.openCheckRiskMode = YES;
config.riskLicense = [[NSBundle mainBundle] pathForResource:@"turing.license" ofType:@""];
注意:
当前的 " turing.license " 文件需要您主动申请,暂时您可以联系客服人员进行 license 申请。将申请完成后的 license 文件放置到当前项目目录下,添加至资源文件 ( copy Bundle Resources ) 中。
2. Token获取配置
在调用 GetFaceIdTokenIntl ApplySdkVerificationToken 接口获取业务 Token 时,需要通过设置 SdkVersion 参数来指定启用增强模式或 Plus 模式:
增强模式:设置对应的 SdkVersion
Plus 模式:设置对应的 SdkVersion
3. 模式启用流程
1)在获取 Token 时设置对应的 SdkVersion 参数;
2)在 SDK 配置中启用设备风控能力;
3)调用 startHuiYaneKYC 方法时传入配置好的 Token;
4) SDK 会根据 Token 中的模式信息自动启用对应的安全级别。
警告:
重要提示:请确保 SDK 配置和 Token 获取两个环节的设置完全一致,否则可能导致模式启用失败。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈