腾讯云人脸识别对接使用完全指南：从开通服务到生产级部署

apphuang2026年07月13日 17:12:1810

1. 人脸识别服务概述

腾讯云神图·人脸识别（Face Recognition）是基于腾讯优图实验室强大的面部分析技术推出的云端人脸识别服务。该服务提供包括人脸检测与分析、人脸比对、人脸搜索、人脸验证、五官定位、活体检测等多种核心功能，为开发者和企业提供高性能、高可用的人脸识别能力。

在技术指标方面，腾讯云人脸识别在2017年LFW测评中准确度高达99.80%，人脸检索在MegaFace竞赛百万规模中首选识别率达到83.29%排名第一。服务可用性可达99.9%，已经通过腾讯内部产品海量用户和复杂场景的验证。即使是百万规模的人脸搜索，仍只需数百毫秒即可处理完毕。

人脸识别2.0版本采用腾讯云API 3.0格式，接口请求域名为iai.tencentcloudapi.com。旧版本（接口请求域名为recognition.image.myqcloud.com或service.image.myqcloud.com）已于2019年6月21日起停止维护，建议尽快升级到2.0版本。

2. 接入前置准备

2.1 注册腾讯云账号

在使用人脸识别服务前，首先需要注册腾讯云账号。如果还没有账号，请参考腾讯云官方注册教程完成账号注册。

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

2.2 实名认证

完成账号注册后，需要进行实名认证。需要特别注意的是，人脸核身服务要求腾讯云账号完成企业实名认证，个人账号无法申请开通人脸核身服务。企业实名认证需要提供营业执照等企业资质信息，审核通常需要1-3个工作日。普通的人脸识别API调用（非核身场景）则支持个人实名认证。

登录腾讯云控制台后，进入账号信息页面，在实名认证配置项下提交认证申请。按照页面提示填写真实姓名、证件类型、证件证号、行业信息和通讯地址等信息。

2.3 开通人脸识别服务

完成实名认证后，登录人脸识别控制台，按照页面提示同意《人脸识别服务规则》后即可开通服务。人脸核身服务则需要登录人脸核身控制台，单击页面上的申请免费试用，按需求填写具体业务信息后提交接入申请。

人脸识别接入需要申请，登录人脸识别控制台单击立即开通即可使用，无需等待人工审核。

2.4 获取API密钥

在调用人脸识别API接口前，需要获取腾讯云API访问密钥（SecretId和SecretKey）。登录腾讯云控制台，进入访问管理 > API密钥管理页面获取密钥。这些密钥是调用API的唯一凭证，请务必妥善保管，不要在代码中硬编码或提交到版本控制系统。

3. API调用方式

腾讯云人脸识别提供三种主要的API调用方式，开发者可以根据自身技术水平和项目需求选择合适的方式。

3.1 API Explorer在线调试

API Explorer是腾讯云提供的在线接口调试工具，适合开发初学者快速体验和验证接口功能。打开人脸识别API 3.0 Explorer在线接口调试页面，选择需要调用的接口并填写输入参数。

API Explorer提供了在线调用、签名验证、SDK代码生成和快速检索接口等能力。您可以在页面左侧选择相应的接口，填写参数后即可发起调用，查看每次调用的请求内容和返回结果。该工具还会自动生成对应语言的SDK调用示例代码，将代码复制即可直接使用。

3.2 SDK集成调用

对于有代码编写基础的开发工程师，推荐通过腾讯云提供的SDK来调用人脸识别服务API。人脸识别2.0版本提供了Python、Java、PHP、Go、Node.js和.NET等多种语言的SDK。您可以在每个服务的文档中下载对应的SDK，也可以通过SDK中心获取。

以下是各语言SDK的安装方式：

  • Python：pip install -U tencentcloud-sdk-python
  • Java：在Maven仓库中查看最新版本号并引入项目
  • PHP：在Composer仓库中查看最新版本号并引入项目
  • Golang：go get -u github.com/tencentcloud/tencentcloud-sdk-go
  • Node.js：npm update tencentcloud-sdk-nodejs --save

3.3 命令行工具

您还可以通过腾讯云命令行工具来调用腾讯云API，管理腾讯云资源；也可以基于腾讯云CLI来做自动化和脚本处理。

4. 核心API接口详解

4.1 人脸检测与分析

人脸检测与分析接口用于检测给定图片中的人脸，返回人脸位置、属性（性别、年龄、表情等）和质量信息。该接口还新增了发型、口罩等人脸属性，以及人脸质量分功能。通过人脸质量分可以判断人脸图片质量，从而决定是否进行下一步的人脸识别操作。

人脸检测还支持返回多达888个稠密关键点，对五官和脸部轮廓进行精确定位。

4.2 人脸比对

人脸比对接口对两张图片中的人脸进行相似度比对，返回人脸相似度分数。该接口仅比对两张图片中人脸的相似度，不涉及人员库。

4.3 人脸验证

人脸验证用于判断给定图片中的人脸是否与人员库中的指定人员为同一人。该接口需要传入一张人脸图片和一个PersonId，判断图片中的人和PersonId对应的人是否为同一人。人脸验证是与人员库打通的功能，验证结果是为了确认“此人”是否是人员库中的某个人。

4.4 人脸搜索

人脸搜索（原名人脸检索）支持百万级人脸搜索。单个腾讯云账号人员库上限由5千提升为2万，单人员库人脸数量上限由2万提升为100万，支持在秒内返回百万级人脸搜索结果。

1个AppID下最多可创建10万个人员库，最多包含5000万张人脸。不同算法模型版本的人员库最多可包含的人脸数不同，算法模型版本为2.0的人员库最多包含100万张人脸。

4.5 五官定位

五官定位（也称人脸关键点定位）对请求图片进行精准的人脸关键点检测，获得人脸的精准信息。该功能可以定位眉毛、眼睛、鼻子、嘴巴等面部关键特征点。

4.6 活体检测

活体检测通过对一段实时录制的自拍视频进行检测，确认当前用户为真人。腾讯云提供多种活体检测方案：

  • 静态活体检测高精度版：相比现有静态活体检测服务，在维持高真人通过率的前提下，增强了对高清屏幕、裁剪纸片、3D面具等攻击的防御能力，攻击拦截率约为业内同类型产品形态的4-5倍
  • 活体人脸比对：传入视频和照片，先判断视频中是否为真人，判断为真人后再判断该视频中的人与上传照片是否属于同一个人
  • 活体人脸核身：传入视频和身份信息，先判断视频中是否为真人，再判断该视频中的人与权威库的证件照是否属于同一个人

5. 人员库管理

5.1 人员库概述

人员库是已知人员身份的人脸库集合。人员库管理是进行人脸验证和人脸搜索的基础。人脸识别2.0版本支持可视化的人员库操作，可以在控制台对人员库进行增删查改等操作。

5.2 创建人员库

在人员管理页面中，单击左上角的新建人员库，根据页面提示填写人员库名称和人员库ID，完成后单击确定即可创建一个人员库。

5.3 创建人员

在人员管理页面中，选择目标人员库名称，单击左上角的创建人员，根据页面提示上传照片并填写人员信息。创建人员时可以添加人脸、姓名、性别及其他相关信息。

UniquePersonControl参数用于控制判断图片中包含的人脸是否在人员库中已有疑似的同一人。如果判断为已有相同人在人员库中，则不会创建新的人员，返回疑似同一人的人员信息。

5.4 增加人脸

将一组人脸图片添加到一个人员中，一个人员最多允许包含5张图片。若该人员存在多个人员库中，所有人员库中该人员图片均会增加。

增加人脸接口的请求域名为iai.tencentcloudapi.com。图片支持base64编码和URL两种传入方式，base64编码后大小不可超过5M。支持PNG、JPG、JPEG、BMP格式，不支持GIF图片。若图片中包含多张人脸，只选取其中人脸面积最大的人脸。

FaceMatchThreshold参数用于控制相似度阈值，只有和该人员已有的人脸相似度超过该值的人脸才能增加成功，默认值60分，取值范围[0,100]。QualityControl参数用于图片质量控制，支持0（不控制）到4（很高要求）多个等级。

6. 人脸核身服务接入

腾讯云人脸核身（也称慧眼人脸核身）是一项基于腾讯优图实验室顶尖人脸识别技术的身份验证服务。该产品通过活体检测、人脸比对、身份证OCR识别等核心技术，帮助企业和开发者快速实现用户的实名身份认证。

人脸核身广泛应用于金融开户、政务办理、在线教育、网约车注册、电商平台实名等需要确认用户真实身份的场景。

6.1 接入模式

人脸核身服务提供两种主要接入模式：

  • SaaS化服务：支持微信小程序、微信H5、微信公众号、微信浮层H5、App SDK、移动端H5等多种渠道接入。开发者只需在控制台配置业务流程并集成SDK即可快速上线
  • PaaS模式：提供纯API接口调用，适用于有自建客户端、需要深度定制核身流程的场景

6.2 接入流程

登录腾讯云人脸核身控制台，在自主接入页面单击创建业务流程。根据业务场景选择应用类型，可选项包括微信小程序、微信H5（微信公众号）、微信浮层H5（微信浏览器）、App SDK、移动端H5等。如果需要在微信场景及非微信场景（如企业微信）使用，需要选择相应的配置选项。

微信小程序接入人脸核身时，需要确认小程序服务类目满足特定要求（如政务民生、教育、医疗、金融业等），并准备好对应的资质文件，资质审核需要5-7个工作日。

6.3 App SDK集成

App端集成相对简单，使用从后端获取的订单号、签名等信息调用SDK即可。后端涉及多个接口开发，需要生成签名等参数供App端使用。

App端流程如下：发起HTTP请求获取服务端生成的签名等参数，然后使用服务端返回的请求参数启动核身SDK。核身完成后，服务端验证结果。

活体人脸比对（App SDK）模式适用于将eKYC的活体人脸比对服务与本地移动应用程序（iOS/Android）集成。Android端慧眼SDK接入需要从慧眼SDK下载链接中下载SDK并集成到本地。

7. 代码示例

7.1 Python SDK示例——人脸检测与分析

from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.iai.v20180301 import iai_client, models

# 实例化认证对象
cred = credential.Credential("你的SecretId", "你的SecretKey")

# 实例化HTTP选项
httpProfile = HttpProfile()
httpProfile.endpoint = "iai.tencentcloudapi.com"

# 实例化客户端配置
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
# 使用TC3-HMAC-SHA256签名方式
clientProfile.signMethod = "TC3-HMAC-SHA256"

# 实例化客户端
client = iai_client.IaiClient(cred, "ap-guangzhou", clientProfile)

# 实例化请求对象
req = models.DetectFaceRequest()
params = {
    "MaxFaceNum": 10,
    "NeedFaceAttributes": 1,
    "NeedQualityDetection": 1,
    "Image": "图片的base64编码数据"
}
req.from_json_string(json.dumps(params))

# 发起请求
resp = client.DetectFace(req)
print(resp.to_json_string())

7.2 Python SDK示例——人脸比对

from tencentcloud.iai.v20180301 import models

# ... 认证和客户端初始化代码同上 ...

req = models.CompareFaceRequest()
params = {
    "ImageA": "第一张图片的base64编码",
    "ImageB": "第二张图片的base64编码",
    "QualityControl": 0
}
req.from_json_string(json.dumps(params))

resp = client.CompareFace(req)
# 返回的相似度分数在0-100之间
print(f"相似度: {resp.Score}")

7.3 Python SDK示例——创建人员库和人员

# 创建人员库
req = models.CreateGroupRequest()
params = {
    "GroupId": "my_group_001",
    "GroupName": "员工人脸库",
    "FaceModelVersion": "2.0"
}
req.from_json_string(json.dumps(params))
resp = client.CreateGroup(req)

# 创建人员
req = models.CreatePersonRequest()
params = {
    "GroupId": "my_group_001",
    "PersonId": "employee_001",
    "PersonName": "张三",
    "Image": "人脸图片base64编码",
    "QualityControl": 0,
    "UniquePersonControl": 0
}
req.from_json_string(json.dumps(params))
resp = client.CreatePerson(req)

7.4 Java SDK示例

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.iai.v20180301.IaiClient;
import com.tencentcloudapi.iai.v20180301.models.*;

public class FaceRecognitionDemo {
    public static void main(String[] args) {
        try {
            Credential cred = new Credential("你的SecretId", "你的SecretKey");
            
            HttpProfile httpProfile = new HttpProfile();
            httpProfile.setEndpoint("iai.tencentcloudapi.com");
            
            ClientProfile clientProfile = new ClientProfile();
            clientProfile.setHttpProfile(httpProfile);
            clientProfile.setSignMethod(ClientProfile.SIGN_TC3_256);
            
            IaiClient client = new IaiClient(cred, "ap-guangzhou", clientProfile);
            
            // 人脸检测
            DetectFaceRequest req = new DetectFaceRequest();
            req.setMaxFaceNum(10L);
            req.setNeedFaceAttributes(1L);
            req.setNeedQualityDetection(1L);
            req.setImage("图片的base64编码数据");
            
            DetectFaceResponse resp = client.DetectFace(req);
            System.out.println(DetectFaceResponse.toJsonString(resp));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

8. 计费模式

腾讯云人脸识别的计费模式为在线API调用。提供两种计费模式：

  • 按QPS计费：适用于需要稳定并发能力的场景
  • 按调用次数计费（默认模式）：每月每种服务均有10000次的免费额度

人员库管理的计费主要包括创建人员和增加人脸两个调用次数合并计费。

9. 常见问题与错误码处理

9.1 签名错误

出现AuthFailure.SignatureFailure签名错误时，建议使用SDK进行调用，因为SDK内含生成签名的代码，可以避免自行组装复杂的签名逻辑。如果使用SDK时出现签名错误，检查是否调用了其他业务的接口。

如果报错提示“exceeding request size limit, please use new signature method TC3-HMAC-SHA256”，原因是默认的签名方式不支持大文件，需要指定新的签名方式：clientProfile.setSignMethod(ClientProfile.SIGN_TC3_256)。

9.2 图片下载错误

图片存储于腾讯云的URL可保障更高下载速度和稳定性，非腾讯云存储的URL速度和稳定性可能受一定影响。如果某个域名下的图片较多报错图片下载错误，建议使用Base64输入图片，或更换URL。

9.3 后端服务超时

API接口调用超时是5秒，包含网络传输时间和服务器处理时间。建议控制图片大小，一般来说人眼能清晰分辨即可，不必过于追求清晰大图。如果是在线图片，建议把图片存储在腾讯云对象存储COS中，可以极大地减少网络传输时间。

9.4 图片中没有人脸

如果返回错误码NoFaceInPhoto，可以先用“人脸检测与分析”接口在线调用，检测图片中人脸大小（Width与Height两个出参），确认MinFaceSize参数是否设置合理。

9.5 限频策略

身份信息认证（二要素核验）中，同一个腾讯云AppId下每个限频字段同一信息（例如同一个姓名），每天核验次数不得超过500次，触发限频策略将会返回相应错误码。

10. 最佳实践建议

10.1 图片质量优化

为获得最佳的识别效果，建议上传的人脸图片满足以下条件：人脸清晰可见，无严重遮挡；图片光线均匀，不过亮或过暗；人脸正对镜头，角度不过偏。可以使用人脸质量分接口预先评估图片质量。

10.2 性能优化

建议将图片存储在腾讯云对象存储COS中，可以保障更高的下载速度和稳定性。对于在线图片URL，非腾讯云存储的URL速度和稳定性可能受一定影响。

控制图片大小，人眼能清晰分辨即可，不必过于追求清晰大图，以减少传输时间和API调用耗时。

10.3 安全建议

API密钥（SecretId和SecretKey）是调用API的唯一凭证，请妥善保管。不要在代码中硬编码密钥，建议使用环境变量或密钥管理服务。生产环境建议使用子账号和最小权限原则进行授权。

10.4 版本选择

人脸识别2.0版本支持腾讯云API 3.0格式，提供了更精准实时的人脸检测、分析、识别与百万级的人脸搜索服务。如果仍在使用1.0版本接口（recognition.image.myqcloud.com或service.image.myqcloud.com），请尽快迁移至2.0版本。

11. 总结

腾讯云人脸识别服务提供了从基础人脸检测到高级人脸核身的完整能力体系。通过API Explorer、多语言SDK和命令行工具等多种调用方式，开发者可以根据自身技术栈和项目需求灵活选择接入方案。人员库管理功能支持大规模人脸数据的组织与检索，活体检测技术确保了身份认证的安全性。无论是简单的1:1人脸比对，还是复杂的1:N人脸搜索和实名核身场景，腾讯云人脸识别都能提供稳定、高效、精准的解决方案。

常见问题问答

问：人脸识别服务是否需要申请才能开通？
答：人脸识别服务登录控制台单击立即开通即可使用，无需等待人工审核。但人脸核身服务需要提交接入申请并进行业务审核。

问：人脸识别支持哪些编程语言的SDK？
答：人脸识别2.0版本提供了Python、Java、PHP、Go、Node.js和.NET格式的SDK。

问：人脸识别每月有多少免费额度？
答：在调用次数计费模式下，每月每种服务均有10000次的免费调用额度。

问：如何快速体验人脸识别接口功能？
答：打开API Explorer，在页面左侧选择相应的接口，填写相应参数即可发起接口调用，无需编写代码。

问：人脸识别接口请求的域名是什么？
答：人脸识别2.0版本接口请求域名为iai.tencentcloudapi.com。

问：一个人脸人员最多可以添加多少张人脸图片？
答：一个人员最多允许包含5张人脸图片。

相关文章

After 10 Years as a Tencent Cloud Agent, Let Me Talk About Rebates

After 10 Years as a Tencent Cloud Agent, Let Me Talk About Rebates

Lately, I’ve been getting a lot of questions from friends: “Does Tencent offer rebates? Can you…

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

一、腾讯云代理商返利机制核心逻辑1. 行业背景与代理模式腾讯云作为国内公有云市场的第二大领导者（据IDC 2025年数据，占据国内27.6%的市场份额），采用渠道商代理模式拓展市场。代理商负…

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

一、腾讯云代理商返利机制核心逻辑1. 行业背景与代理模式腾讯云作为国内公有云市场的第二大领导者（据IDC 2025年数据，占据国内27.6%的市场份额），采用渠道商代理模式拓展市场。代理商负…

2026腾讯云代理商返佣政策全解析：五级代理体系与企业上云成本优化指南

2026腾讯云代理商返佣政策全解析：五级代理体系与企业上云成本优化指南

一、腾讯云五级代理体系：权益阶梯与合作价值1. 五级代理的核心权益差异腾讯云按规模、服务能力与合作深度，构建了从基础到顶级的五级代理体系，各级权益呈现显著阶梯差：•标准级代理：入门门槛最低，仅能提供基…

上海汪远信息：全国Top5腾讯云代理商，10年深耕为企业上云保驾护航

上海汪远信息：全国Top5腾讯云代理商，10年深耕为企业上云保驾护航

核心摘要本文深度解析腾讯云代理商行业现状，揭示小代理商生存困境的核心原因（低业绩导致提成少、厂商压款、市场淘汰），重点推荐上海汪远信息科技有限公司——一家拥有10年腾讯云代理经验、年销量超2亿的全国T…

上海汪远信息科技：10年腾讯云头部代理商，全国前五，7折优惠+稳定服务保障

上海汪远信息科技：10年腾讯云头部代理商，全国前五，7折优惠+稳定服务保障

 核心摘要本文深度解析腾讯云代理商的定义、行业竞争格局（红海市场，头部稀缺，小代理商因资金压力易倒闭），揭示企业选择腾讯云代理商的核心需求（稳定优惠、技术支持、成本优化），重点推荐上海汪远信…

上海汪远信息科技有限所在公司从事多年公有云和电子签代理，能持续为用户提供商务价值和技术支持，目前从事的代理有：阿里云，腾讯云，华为云，火山云，天翼云，移动云，亚马逊云，谷歌云，微软云，腾讯电子签，法大大电子签，爱签电子签等！

网站备案号：沪ICP备15020509号-2 公安备案号：沪公网安备31011202008721号