全部产品
Search

搜索本产品

    ID Verification：Initialize

    文档中心

    ID Verification：Initialize

    更新时间：Feb 06, 2026

    本文介绍如何通过调用Initialize接口发起认证请求。

    发起认证请求

    • 接口名：Initialize

    • 请求方法：HTTPS POST

    • 接口说明：每次开始认证流程前，通过本接口获取transactionId，用来串联认证请求中的各个接口。

    • QPS限量：API独享QPS限量，详情请参见ID Verification服务端API QPS限量说明。

    • 服务地址：

      说明

      • 内网访问优势：内网指阿里云同一地域内各产品间的私有通信网络。若您的业务服务器部署于阿里云对应地域，请使用内网域名访问 ID Verification 服务，以获得更安全、稳定的通信质量。 

      • 海外访问优化建议：海外网络环境复杂，建议参考服务端网络耗时分析与优化，优化集成方案，降低网络延迟及请求失败概率。

      新加坡

      • 公网：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代码示例。

    请求参数

    名称

    类型

    是否必选

    描述

    示例值

    ProductCode

    String

    是

    要接入的产品方案。唯一取值：FACE_IDU。

    FACE_IDU

    SceneCode

    String

    否

    您自定义的认证场景ID，用于后续控制台输入此场景ID查询相关记录。支持长度为10位的字母、数字或下划线的组合。

    1234567890

    MetaInfo

    String

    是

    MetaInfo环境参数，需要通过客户端 SDK 调用函数 getMetaInfo() 获取，请参考对应平台的客户端接入文档，获取MetaInfo。

    说明

    无须修改返回值，直接透传即可。

    {
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "ios",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

    SecurityLevel

    String

    否

    代表认证流程不同安全水位的模式，可选值：

    • 01：普通模式，仅适用低风险且对设备信息采集限制的场景。

    • 02：安全模式，相对严格的模式（默认）。

      说明

      • 安全模式通过 SDK 新增的设备助手模块，基于设备信息识别刷脸环境的安全性，有效提升对注入攻击的拦截能力。建议启用此模式。

      • 在开发测试阶段，测试设备的环境特征可能导致设备安全助手判定存在风险，从而触发认证失败（Subcode 206）。建议在测试期间将模式手动设置为“01 普通模式”，以提升测试效率；正式上线时切换为“02 安全模式”，以增强认证安全性。

    02

    Model

    String

    否

    要进行活体检测的类型：

    • LIVENESS：眨眼动作活体检测（默认）。

    • PHOTINUS_LIVENESS：眨眼动作活体检测和炫彩活体（PC端不支持）检测。

    说明

    支持集成的SDK版本，请参见SDK发布记录。

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存证视频。

    • N：不需要（默认）。

    • Y：认证过程中会同时采集用户的刷脸过程视频（1~2s视频文件），并通过查询接口返回。

    说明

    因为视频文件较大，当网络不稳定时系统会丢弃视频文件，优先保障认证必要图片传输。

    N

    CallbackUrl

    String

    否

    认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以https开头。平台在完成认证后会回调该地址，并自动添加以下字段：

    • transactionId

    • passed

    • subcode

    警告

    • 此值的传入会在调用接口前做可访问校验，如果传入的地址不能在公网访问，会返回400。

    • 回调会在认证完成后立即执行，但可能会因为网络等原因延迟，建议您优先接收客户端侧的认证完成通知，再请求查询接口获取认证详情。

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    否

    安全Token，由您自行生成，用于防重复、防篡改校验。

    如果设置了此值，将会在CallbackUrl回调时携带CallbackToken字段。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    否

    是否开启人脸严格质量检测：

    • Y：开启（默认）

    • N：不开启

    重要

    • 此配置需要客户端SDK的支持，如果设置开启，但客户端SDK没有集成人脸质量检测模块，则此配置视同不开启。

    • 客户端SDK版本需要1.2.5及以上版本。

    N

    VerifyModel

    String

    否

    验证类型：

    • 0：检索模式

      • 功能：传入指定人脸库，用户完成客户端刷脸动作时，系统自动检索指定的人脸库中是否已经存该人脸图片。

      • 建议场景：真人注册账号且不允许重复注册场景。

    • 1（默认）：验证模式

      • 功能：传入指定人脸图片，用户完成客户端刷脸动作时，系统自动验证是否与指定的人脸一致。

      • 建议场景：登录、账号信息修改等需要是否验证是否本人操作的场景。

    • 2：综合模式

      • 功能：同时传入指定人脸库与人脸图片，用户完成客户端刷脸动作时，系统自动检索指定的人脸库中是否已经存该人脸图片，是否指定人脸本人。

      • 建议场景：需要验证是新增用户且是本人操作场景。

    0

    FaceGroupCodes

    String

    否

    通过ID Verification产品控制台创建人脸库时获取对应编码，最大支持同时查询10个人脸库。当传入多个人脸库编码时，以逗号区分。

    说明

    当 VerifyModel = 1或2 时必传。

    sg*****xta，s*****uk3j

    TargetFacePicture

    String

    否

    人像照片Base64编码。

    指作为比对源可信人脸图片，可选传入。

    说明

    当 VerifyModel = 1或2 时必传。

    -

    TargetFacePictureUrl

    String

    否

    人像图片地址，公网可访问的HTTP、HTTPS链接。

    -

    MerchantUserId

    String

    是

    您自定义的用户唯一ID，或者其他可以识别特定用户的标识，例如：手机号码、邮箱地址等。

    说明

    强烈建议对该字段的值进行预先脱敏，例如对值进行哈希处理，并且保持唯一性。

    123456789

    AutoRegistration

    String

    否

    验证通过时是否自动注册到指定人脸库：

    • 0：自动注册

    • 1（默认）：不注册

    0

    FaceRegisterGroupCode

    String

    否

    当开启自动注册人脸功能且存在多个人脸库时，需要通过该参数传入指定的人脸库编码。

    sg*****xta

    ReturnFaces

    String

    否

    指匹配阈值之上存在多个人脸时，可通过该参数自定义返回数量

    默认返回1 ，最大支持5。

    说明

    当VerifyModel = 1时，该参数不生效。

    1

    FaceVerifyThreshold

    String

    否

    人脸验证阈值。

    说明

    预留字段，暂未开放。

    0.4

    返回数据

    名称

    类型

    描述

    示例值

    HTTP Status Code

    Integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    String

    请求ID。

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

    Code

    String

    返回Code。

    Success

    Message

    String

    返回Code的详细描述。

    success

    Result.TransactionId

    String

    整个认证流程的唯一标识。该字段为计费统计字段，并用于发起CheckResult接口请求。

    重要

    • 当请求过程中出现错误时，例如参数无效，则不会返回TransactionId。

    • 建议将TransactionId与您本次业务流程的业务ID绑定并存储在服务端，在CheckResult时从您服务端存储提取该认证ID，发起结果查询。

    • 获取TransectionId或TransactionUrl成功后，需要在30分钟内完成认证，超过时间将自动失效无法再认证。

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    认证标准加密协议。

    建议获取该参数并传递给客户端 SDK。客户端 SDK 将基于此参数减少网络交互，并支持动态网络切换，以提升用户体验。

    hksb7ba1b28130d24e015d*********

    返回Code

    HTTP Status Code

    Code

    描述

    200

    Success

    请求成功。

    400

    MissingParameter

    参数不能为空。

    400

    InvalidParameter

    非法参数。

    401

    NoFaceDetected

    自定义比对源的图片人脸特征提取失败，建议更换图片上传。

    401

    UnqualifiedPhoto

    传入的图片不可读，或图片分辨率不符合要求，建议更换图片。需确保照片清晰、曝光正常，完整无遮挡，角度无太大偏差。

    401

    ToolargeImage

    图片尺寸过大，建议压缩图片或更换图片上传方式。

    401

    DataDuplication

    同时通过Base64方式与链接方式传入图片。

    401

    DownloadTimeout

    URL图片下载超时。

    403

    Forbidden.RAMUserAccessDenied

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

    403

    Forbidden.AccountAccessDenied

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

    403

    Throttling.Api

    API限流拦截。

    500

    InternalError

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