对象存储
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 对象存储 > SDK 文档 > Go SDK > AI 内容识别 > 人脸核身

人脸核身

最近更新时间：2023-07-24 09:55:14

我的收藏

本页目录：

简介

本文档提供关于人脸核身的 API 概览以及 SDK 示例代码。
API
操作描述
支持中国大陆居民二代身份证正反面所有字段的识别，包括姓名、性别、民族、出生日期、住址、公民身份证号、签发机关、有效期限；具备身份证照片、人像照片的裁剪功能和翻拍、PS、复印件告警功能，以及边框和框内遮挡告警、临时身份证告警和身份证有效期不合法告警等扩展功能
使用动作活体检测模式前，需调用本接口获取动作顺序
使用数字活体检测模式前，需调用本接口获取数字验证码
集成了活体检测和跟权威库进行比对的能力，传入一段视频和姓名、身份证号信息即可进行验证。对录制的自拍视频进行活体检测，从而确认当前用户为真人，可防止照片、视频、静态3D建模等各种不同类型的攻击。检测为真人后，再判断该视频中的人与权威库的证件照是否属于同一个人，实现用户身份信息核实

身份证识别

功能说明

中国大陆居民二代身份证正反面所有字段的识别。

方法原型

func (s *CIService) IdCardOCRWhenCloud(ctx context.Context, key string, query *IdCardOCROptions) (*IdCardOCRResult, *Response, error) // 云上数据处理
func (s *CIService) IdCardOCRWhenUpload(ctx context.Context, key, filePath string, query *IdCardOCROptions, header *ObjectPutOptions) (*IdCardOCRResult, *Response, error) // 上传时处理

请求示例1：云上数据处理

key := "pic/idcard_1.png"
query := &cos.IdCardOCROptions{
    Config: &cos.IdCardOCROptionsConfig{
        CropPortrait:    true,
        CropIdCard:      true,
        CopyWarn:        true,
        BorderCheckWarn: true,
        ReshootWarn:     true,
        DetectPsWarn:    true,
        TempIdWarn:      true,
        InvalidDateWarn: true,
        Quality:         true,
        MultiCardDetect: true,
    },
}
res, _, err := c.CI.IdCardOCRWhenCloud(context.Background(), key, query)

参数说明

type IdCardOCROptions struct {
    CardSide string                  `url:"CardSide,omitempty"`
    Config   *IdCardOCROptionsConfig `url:"Config,omitempty"`
}

type IdCardOCROptionsConfig struct {
    CropIdCard      bool `json:"CropIdCard,omitempty"`
    CropPortrait    bool `json:"CropPortrait,omitempty"`
    CopyWarn        bool `json:"CopyWarn,omitempty"`
    BorderCheckWarn bool `json:"BorderCheckWarn,omitempty"`
    ReshootWarn     bool `json:"ReshootWarn,omitempty"`
    DetectPsWarn    bool `json:"DetectPsWarn,omitempty"`
    TempIdWarn      bool `json:"TempIdWarn,omitempty"`
    InvalidDateWarn bool `json:"InvalidDateWarn,omitempty"`
    Quality         bool `json:"Quality,omitempty"`
    MultiCardDetect bool `json:"MultiCardDetect,omitempty"`
}
参数名称
参数描述
是否必填
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/pic/pic.jpg中，对象键为 pic/pic.jpg
是
CardSide
FRONT：身份证有照片的一面（人像面） BACK：身份证有国徽的一面（国徽面） 该参数如果不填，将为您自动判断身份证正反面
否
CropIdCard
身份证照片裁剪（去掉证件外多余的边缘、自动矫正拍摄角度）
否
CropPortrait
人像照片裁剪（自动抠取身份证头像区域）
否
CopyWarn
复印件告警
否
BorderCheckWarn
边框和框内遮挡告警
否
ReshootWarn
翻拍告警
否
DetectPsWarn
PS 检测告警
否
TempIdWarn
临时身份证告警
否
InvalidDateWarn
身份证有效日期不合法告警
否
Quality
图片质量分数（评价图片的模糊程度）
否
MultiCardDetect
是否开启多卡证检测
否

请求示例2：上传时处理

key := "pic/idcard_0.png"
filePath := "./idcard_0.png"
query := &cos.IdCardOCROptions{
    Config: &cos.IdCardOCROptionsConfig{
        CropPortrait:    true,
        CropIdCard:      true,
        CopyWarn:        true,
        BorderCheckWarn: true,
        ReshootWarn:     true,
        DetectPsWarn:    true,
        TempIdWarn:      true,
        InvalidDateWarn: true,
        Quality:         true,
        MultiCardDetect: true,
    },
}

res, _, err := c.CI.IdCardOCRWhenUpload(context.Background(), key, filePath, query, nil)

参数说明

参数名称
参数描述
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/pic/pic.jpg中，对象键为 pic/pic.jpg
filePath
本地文件路径
query
身份证识别相关选项
header
对象上传参数，详见 上传对象

结果说明

type IdCardOCRResult struct {
    XMLName      xml.Name            `xml:"Response"`
    IdInfo       *IdCardInfo         `xml:"IdInfo,omitempty"`
    AdvancedInfo *IdCardAdvancedInfo `xml:"AdvancedInfo,omitempty"`
}

type IdCardInfo struct {
    Name      string `xml:"Name,omitempty"`
    Sex       string `xml:"Sex,omitempty"`
    Nation    string `xml:"Nation,omitempty"`
    Birth     string `xml:"Birth,omitempty"`
    Address   string `xml:"Address,omitempty"`
    IdNum     string `xml:"IdNum,omitempty"`
    Authority string `xml:"Authority,omitempty"`
    ValidDate string `xml:"ValidDate,omitempty"`
}

type IdCardAdvancedInfo struct {
    IdCard          string   `xml:"IdCard,omitempty"`
    Portrait        string   `xml:"Portrait,omitempty"`
    Quality         string   `xml:"Quality,omitempty"`
    BorderCodeValue string   `xml:"BorderCodeValue,omitempty"`
    WarnInfos       []string `xml:"WarnInfos,omitempty"`
}
参数名称
参数描述
Name
姓名（人像面）
Sex
性别（人像面）
Nation
民族（人像面）
Birth
出生日期（人像面）
Address
地址（人像面）
IdNum
身份证号（人像面）
Authority
发证机关（国徽面）
ValidDate
证件有效期（国徽面）
IdCard
裁剪后身份证照片的 Base64 编码，设置 Config.CropIdCard 为 true 时返回
Portrait
身份证头像照片的 Base64 编码，设置 Config.CropPortrait 为 true 时返回
Quality
图片质量分数，设置 Config.Quality 为 true 时返回（取值范围：0~100，分数越低越模糊，建议阈值≥50）
BorderCodeValue
身份证边框不完整告警阈值分数，设置 Config.BorderCheckWarn 为 true 时返回（取值范围：0~100，分数越低边框遮挡可能性越低，建议阈值≥50）
WarnInfos
告警信息，Code 告警码列表和释义：
9100 身份证有效日期不合法告警
9101 身份证边框不完整告警
9102 身份证复印件告警
9103 身份证翻拍告警
9104 临时身份证告警
9105 身份证框内遮挡告警
9106 身份证 PS 告警
可能存在多个 WarnInfos

获取动作顺序

功能说明

获取动作顺序。

方法原型

func (s *CIService) GetActionSequence(ctx context.Context) (*GetActionSequenceResult, *Response, error)

请求示例

res, _, err := c.CI.GetActionSequence(context.Background())

参数说明

无。

结果说明

type GetActionSequenceResult struct {
    XMLName        xml.Name `xml:"Response"`
    ActionSequence string   `xml:"ActionSequence,omitempty"`
}
参数名称
参数描述
ActionSequence
动作顺序（2，1 or 1，2）。1代表张嘴，2代表闭眼

获取数字验证码

功能说明

获取数字验证码。

方法原型

func (s *CIService) GetLiveCode(ctx context.Context) (*GetLiveCodeResult, *Response, error)

请求示例

res, _, err := c.CI.GetLiveCode(context.Background())

参数说明

无。

结果说明

type GetLiveCodeResult struct {
    XMLName  xml.Name `xml:"Response"`
    LiveCode string   `xml:"LiveCode,omitempty"`
}
参数名称
参数描述
LiveCode
数字验证码，如：1234

活体人脸核身

功能说明

对录制的自拍视频进行活体检测。

方法原型

func (s *CIService) LivenessRecognitionWhenCloud(ctx context.Context, key string, query *LivenessRecognitionOptions) (*LivenessRecognitionResult, *Response, error) // 云上数据处理
func (s *CIService) LivenessRecognitionWhenUpload(ctx context.Context, key, filePath string, query *LivenessRecognitionOptions, header *ObjectPutOptions) (*LivenessRecognitionResult, *Response, error) // 上传时处理

请求示例1：云上数据处理

key := "pic/self.mp4"
query := &cos.LivenessRecognitionOptions{
    IdCard:       "111222xxxxxxxxxxxx",
    Name:         "张三",
    LivenessType: "SILENT",
    BestFrameNum: 2,
}
res, _, err := c.CI.LivenessRecognitionWhenCloud(context.Background(), key, query)

参数说明

type LivenessRecognitionOptions struct {
    IdCard       string `url:"IdCard,omitempty"`
    Name         string `url:"Name,omitempty"`
    LivenessType string `url:"LivenessType,omitempty"`
    ValidateData string `url:"ValidateData,omitempty"`
    BestFrameNum int    `url:"BestFrameNum,omitempty"`
}
参数名称
参数描述
是否必填
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/pic/pic.jpg中，对象键为 pic/pic.jpg
是
IdCard
身份证号
是
Name
姓名。中文请使用 UTF-8编码
是
LivenessType
活体检测类型，取值：LIP/ACTION/SILENT
LIP 为数字模式，ACTION 为动作模式，SILENT 为静默模式，三种模式选择一种传入
是
ValidateData
数字模式传参：数字验证码（1234），需先调用接口获取数字验证码
动作模式传参：传动作顺序（2，1 or 1，2），需先调用接口获取动作顺序
静默模式传参：空
是。当 LivenessType 填的是 SILENT 时，该参数为可选项
BestFrameNum
需要返回多张最佳截图，取值范围1 - 10，不设置默认返回一张最佳截图
否

请求示例2：上传时处理

key := "pic/self.mp4"
filePath := "./self.mp4"
query := &cos.LivenessRecognitionOptions{
    IdCard:       "111222xxxxxxxxxxxx",
    Name:         "张三",
    LivenessType: "SILENT",
    BestFrameNum: 2,
}
res, _, err := c.CI.LivenessRecognitionWhenUpload(context.Background(), key, filePath, query, nil)

参数说明

参数名称
参数描述
key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/pic/pic.jpg中，对象键为 pic/pic.jpg
filePath
本地文件路径
query
活体人脸检测相关选项
header
对象上传参数，详见 上传对象

结果说明

type LivenessRecognitionResult struct {
    XMLName         xml.Name `xml:"Response"`
    BestFrameBase64 string   `xml:"BestFrameBase64,omitempty"`
    Sim             float64  `xml:"Sim,omitempty"`
    BestFrameList   []string `xml:"BestFrameList,omitempty"`
}
参数名称
参数描述
BestFrameBase64
验证通过后的视频最佳截图照片，照片为 BASE64 编码后的值，JPG 格式 注意：此字段可能返回 null，表示取不到有效值
Sim
相似度，取值范围 [0.00，100.00]。推荐相似度大于等于70时可判断为同一人，可根据具体场景自行调整阈值（阈值70的误通过率为千分之一，阈值80的误通过率是万分之一）
检测成功返回
BestFrameList
最佳截图列表，仅在配置了返回多张最佳截图时返回 注意：此字段可能返回 null，表示取不到有效值

中国站