全部产品
Search

搜索本产品

    ID Verification：添加人脸图片到指定人脸库

    文档中心

    ID Verification：添加人脸图片到指定人脸库

    更新时间：Apr 01, 2026

    FACE_IDU 支持人脸检索模式。您可通过 ID Verification 控制台创建人脸库并添加人脸图片，也可通过本接口实现人脸图片的添加。

    接口信息

    • 接口名：AddFaceRecord

    • 请求方法：POST

    • 传输协议：HTTPS

    • QPS 限制：该 API 对单个租户的请求速率上限为 50 QPS。

    • 服务地址：

      说明

      • 内网指的是阿里云同地域产品之间的内部通信网络，如果您的业务服务器部署在阿里云的对应地域，可以通过内网域名访问 ID Verification 服务，以获得更安全、稳定的网络通信质量。

      • ID Verification不同产品方案支持的Region不同，数据之间相互隔离，您需要选择数据所在Reigon下的接口域名，才能成功访问数据。

      新加坡

      • 公网：cloudauth-intl.ap-southeast-1.aliyuncs.com

      • 内网：cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      印度尼西亚

      • 公网：cloudauth-intl.ap-southeast-5.aliyuncs.com

      • 内网：cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      中国香港

      • 公网：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 内网：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      马来西亚（吉隆坡）

      • 公网：cloudauth-intl.ap-southeast-3.aliyuncs.com

      • 内网：cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    在线调试和集成

    说明

    在调试和集成前，请确保您已完整阅读使用OpenAPI调试和集成服务端API文档，充分了解API接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。

    您可以在OpenAPI Explorer中直接运行本接口进行调试，并生成本接口的SDK代码示例。

    图片上传要求

    • 图片格式：JPG，JPEG。

    • 图片大小：推荐50~100 KB，最大不超过10 MB（建议超过1MB的图片可以通过URL或文件流的方式上传）。

    • 图片分辨率：建议640*480（高*宽），不超过1920*1080（高*宽），且保持照片的高大于宽。推荐短边缩放到720像素，压缩率0.8。

    • 图片质量：照片清晰、曝光正常，脸部无过黑、过亮、光晕等情况。

    • 图片人脸：当图片出现多个人脸时，系统将默认检测图中面积最大的人脸。

    请求参数

    说明

    上传注册人脸图片时，FacePicture、FacePictureUrl、FacePictureFileObject三种方式任选其一即可。

    名称

    类型

    描述

    是否必填

    示例值

    ProductCode

    string

    产品代码。固定值：FACE_ENROLL

    是

    FACE_ENROLL

    FaceGroupCode

    string

    人脸库编码。

    是

    sgl****7uc

    MerchantUserId

    string

    自定义的用户唯一ID，不能超过32位。

    • 若传入则优先以该userID注册；

    • 若未传入则选择默认图片名。

    否

    130A2C10B9EE4D8488E35384FF03hst

    FacePicture

    string

    人脸图片的base64编码。

    否

    base64

    FacePictureUrl

    string

    人脸图片的URL。

    否

    https://example.com/test.jpg

    FacePictureFileObject

    InputStream

    人脸图片的本地文件流。

    使用此方式上传时，需通过云产品提供的 Advance 接口进行调用，并传入有效的 InputStream 对象。具体实现，请参见特殊场景：文件上传 Advance 接口配置。

    否

    图⽚的InputStream对象

    FaceQualityCheck

    string

    是否检测人脸图片质量。

    • Y：开启 

    • N：关闭（默认）

    说明

    储备功能，暂不支持。

    否

    N

    返回参数

    名称

    类型

    描述

    示例值

    HTTP Status Code

    integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    string

    请求ID。

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    string

    返回Code。

    Success

    Message

    string

    返回Code的详细描述。

    请求成功

    Result.Passed

    string

    注册结果。

    • Y：注册成功

    • N：注册失败

    Y

    Result.ExtFaceInfo

    string

    注册相关结果信息，关于JSON格式，请参见右侧示例。

    更多信息，请参见ExtFaceInfo。

    {
  "faceQuality": "HIGH"
}

    ExtFaceInfo

    名称

    类型

    描述

    示例值

    faceQuality

    string

    图像质量。

    • HIGH：质量正常

    • LOW：质量不佳

    HIGH

    返回码

    HTTP状态码

    Code

    Message描述

    200

    Success

    请求成功。

    400

    MissingParameter

    参数不能为空。

    InvalidParameter

    非法参数。

    403

    Forbidden.RAMUserAccessDenied

    需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。更多信息，请参见授权RAM用户访问服务。

    Forbidden.AccountAccessDenied

    确保您开通了ID verification，并且保证账户未欠费。

    Throttling.Api

    API限流拦截。

    500

    InternalError

    系统内部错误，请反馈工程师排查。

    503

    ServiceUnavailable

    服务不可用，请反馈工程师排查。