全部产品
Search

搜索本产品

    ID Verification：InitializeV2

    文档中心

    ID Verification：InitializeV2

    更新时间：Sep 29, 2026

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

    接口信息

    • 接口名：InitializeV2

    • 请求方法：HTTPS POST

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

    • QPS限量：API独享QPS限量，详情请参见服务端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接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。

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

    接入注意事项

    • 仅当初始化成功时返回 TransactionId。客户端须在获取 TransactionId 或 TransactionUrl 后的 30 分钟内完成认证。

    • TransactionUrl 仅在 Web SDK 场景下返回，且仅限单次使用，严禁拼接、改写或重复访问。

    • 受网络延迟影响，CallbackUrl 通知可能存在滞后。客户端在接收到认证完成通知后，必须调用服务端 CheckResult 接口以获取最终认证详情，严禁仅依赖回调通知或页面展示结果。

    • App SDK 与 Web SDK 的功能存在差异；同时，Web SDK 在移动端 H5 与 PC 端的表现亦有少量区别。具体功能支持情况，请以接入文档的说明为准。

    请求参数

    请求字段说明

    集成方式

    适用场景

    初始化接口返回

    请求参数

    App SDK

    Android / iOS 原生 App 内完成认证

    TransactionId、Protocol

    共有参数 + App 特有参数

    Web SDK

    移动端 H5 、App 内嵌 H5或 PC 浏览器认证

    TransactionId、TransactionUrl、Protocol

    共有参数 + Web SDK特有参数

    字段归类如下：

    • 共有基础参数：两种集成方式均可传入。

    • App 特有：用于自定义活体动作流程。

    • Web SDK 特有：用于页面回跳、语言 / UI与 H5 降级行为控制。

    请求参数（共有）

    名称

    类型

    是否必选

    描述

    示例值

    ProductCode

    String

    是

    产品方案标识，固定取值：FACE_LIVENESS_PRO。

    FACE_LIVENESS_PRO

    SceneCode

    String

    否

    自定义认证场景 ID；用于后续在控制台输入此ID进行记录检索。支持长度为10位的字母、数字或下划线组合。

    1234567890

    MerchantBizId

    String

    是

    商户业务唯一标识，用于后续定位排查问题。支持32 位字母和数字组合。服务端不校验此ID唯一性，商户应自行保证唯一。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    客户端环境信息。建议由对应 SDK 生成；若自行构造，至少须正确传入 deviceType。

    示例代码：

    {
  "deviceType": "h5"
}

    deviceType 取值说明：

    • Android 原生 App：android

    • iOS 原生 App：ios

    • H5 内嵌页面：h5

    • PC 浏览器网页：web

    重要

    建议通过认证 SDK 获取 MetaInfo，以获取更准确、详细的客户端信息，从而支持认证 URL 下发、日志排查及安全校验等场景。若自行构造 MetaInfo 固定值，请务必确保 deviceType 与实际接入环境一致，填写错误将导致认证 URL 下发异常。

    {
  "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"
}

    MerchantUserId

    String

    是

    商户自定义的用户标识，或其他可识别用户的标识，例如手机号码、邮箱地址等。建议预先对该字段进行脱敏或哈希处理。

    123456789

    CallbackUrl

    String

    否

    认证结果回调地址，必须以 https 开头。平台通过 GET 回调并追加 transactionId、passed、subcode。

    若此地址公网不可访问，则会返回 400 报错。

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

    CallbackToken

    String

    否

    商户自定义安全令牌；设置后将会原样随CallbackUrl返回，用于防重放、防篡改校验。

    NMjvQanQgplBSaEI0sL********

    SecurityLevel

    String

    否

    安全等级：

    • 01：普通（仅建议测试环境使用 ，以提升测试效率）

    • 02：安全（默认，强烈建议生产环境使用）

    02

    Model

    String

    否

    【刷脸配置】活体检测类型：

    • SILENT：静默（Naive SDK 1.3.6及以上支持）

    • LIVENESS：眨眼（默认）

    • PHOTINUS_LIVENESS：眨眼+炫彩（PC模式不支持）

    • TEMPLATE：自定义活体检测动作（Web SDK不支持，Naive SDK 1.3.6及以上支持）

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    【刷脸配置】是否采集 1–2 秒人脸过程存证视频：

    • Y：是

    • N：否（默认）

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

    输出结果请在Checkresult中查看Result.ExtFaceInfo.docVideoUrl

    N

    FaceAttributeCheck

    String

    否

    【刷脸配置】是否返回额外的人脸属性：

    • N：不返回（默认）

    • Y：返回

    输出结果在Checkresult中查看Result.ExtFaceInfo.faceAttributeInfo

    N

    ShowGuidePage

    String

    否

    【UI配置】是否展示引导页：

    • 1：展示（默认）

    • 0：不展示

    PC模式不支持此配置。

    Native SDK 1.4.0及以上版本支持。

    1

    请求参数（App 接入特有）

    仅原生 App SDK 支持以下字段。

    名称

    类型

    是否必选

    描述

    示例值

    AppQualityCheck

    String

    否

    【刷脸配置】是否开启人脸严格质量检测：

    • Y：开启（默认）

    • N：不开启

    仅NativeSDK 版本1.2.5 以上且集成人脸质量检测模块支持。

    N

    TemplateConfig

    String

    条件必选

    【刷脸配置】自定义动作池。当 Model 为 TEMPLATE 时，需传入此参数。

    • 配置规则：多个动作代码使用英文逗号分隔。

    • 最佳实践：必须包含眨眼动作，多动作总数不超过 3 个。

    动作代码表：

    • 眨眼：01（必选）

    • 张嘴：02

    • 左摇头：03

    • 右摇头：04

    • 拉远摄像头：05

    • 拉近摄像头：06

    • 炫彩检测：07

    Native SDK 1.3.6及以上支持。

    01,02,07

    TemplateType

    String

    条件必选

    【刷脸配置】TemplateConfig活体检测动作执行顺序。

    当 Model 为 TEMPLATE 时，需传入此参数。

    • Seq：按TemplateConfig配置的顺序从左至右执行。

    Native SDK 1.3.6及以上支持。

    Seq

    请求参数（Web SDK 接入特有）

    仅 Web SDK 支持以下字段。

    字段

    类型

    必选

    说明

    示例值

    LanguageConfig

    String

    否

    自定义语言配置。根据配置模板，将需新增的语言配置转换为JSON字符串后，通过该接口传入实现自定义配置。更多详情，请参见Web SDK 自定义语种。

    说明

    目前仅适用于Web SDK 移动端集成模式，PC模式暂不支持。

    {
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

    StyleConfig

    String

    否

    自定义UI配置。根据配置模板，将您自定义的UI配置转换为JSON字符串后，通过该接口传入实现。更多信息，请参见IDV UI样式自定义。

    说明

    目前仅适用于Web SDK 移动端集成模式，PC模式暂不支持。

    {
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

    ReturnUrl

    String

    条件必选

    认证结束后的业务回跳地址。使用 iframe 内嵌模式时非必填；非 iframe 页面跳转场景应提供。

    https://www.alibabacloud.com

    ProcedurePriority

    String

    否

    当移动端H5方式认证出现兼容性问题时，是否允许展示降级的处理方式。

    • url：支持降级。页面展示认证URL，用户可复制URL打开或者切换浏览器继续认证（默认）。

    • keep：不支持降级。直接返回错误原因，并结束认证流程。PC端不支持，App 内嵌网页建议设为 keep。

    url

    返回数据

    返回字段差异说明

    字段

    App SDK

    Web SDK

    说明

    RequestId / Code / Message

    是

    是

    通用响应信息。

    Result.TransactionId

    是

    是

    认证流程唯一标识、计费统计字段，也是后续 CheckResult 的请求参数。建议与商户业务 ID 绑定后仅保存在服务端。

    Result.Protocol

    是

    是

    认证标准加密协议。建议透传给客户端 SDK；Web SDK iframe 内嵌方式依赖该字段。

    Result.TransactionUrl

    否

    是

    Web SDK认证 URL，认证后按 ReturnUrl 回跳。不可修改、仅能访问一次；获取到 URL 或 TransactionId 后须在 30 分钟内完成认证。

    名称

    类型

    描述

    示例值

    HTTP Status Code

    Integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    String

    请求ID。

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

    Code

    String

    返回Code，具体信息请参见服务端返回HTTP状态码说明。

    Success

    Message

    String

    返回Code的详细描述。

    success

    Result.TransactionId

    String

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

    重要

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

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

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

    hksb7ba1b28130d24e015d6********

    Result.TransactionUrl

    String

    Web SDK认证URL，认证结束后根据入参ReturnUrl进行跳转。

    重要

    • 集成过程中，不要对TransactionUrl做任何操作或修改，否则会导致认证异常。

    • 为保障认证过程安全有效，TransactionUrl仅能使用一次，重复访问也将导致认证异常。

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

    https://www.alibabacloud.com/index.html?clientcfg=****

    Result.Protocol

    String

    认证标准加密协议。

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

    hksb7ba1b28130d24e015d*********

    请求示例

    App SDK

    最小请求示例

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5ac***e6ed20c35",
  "MetaInfo": "{\"deviceType\":\"android\"}",
  "MerchantUserId": "user_hash_value"
}

    完整请求示例

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"bioMetaInfo\":\"4.1.0:1150****,0\",\"appName\":\"com.aliyun.antcloudauth\",\"deviceType\":\"android\",\"osVersion\":\"Android 12\",\"apdidToken\":\"\",\"deviceModel\":\"Pixel 6\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "TEMPLATE",
  "DocVideo": "Y",
  "FaceAttributeCheck": "Y",
  "ShowGuidePage": "1",
  "AppQualityCheck": "Y",
  "TemplateConfig": "01,02,07",
  "TemplateType": "Seq",
  "TemplateRanCount": "2"
}

    Web SDK

    最小请求示例

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5a***6ed20c35",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "ReturnUrl": "https://example.com/liveness/result"
}

    完整请求示例

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "PHOTINUS_LIVENESS",
  "DocVideo": "N",
  "FaceAttributeCheck": "N",
  "LanguageConfig": "{\"languageContent\":{},\"ocrResultContent\":{},\"supportedLanguage\":[\"zh-CN\"],\"titleTranslate\":{}}",
  "StyleConfig": "{\"guidepage\":{},\"ocrPage\":{},\"ocrResultPage\":[],\"facePage\":{}}",
  "ShowGuidePage": "1",
  "ReturnUrl": "https://www.example.com/liveness/result",
  "ProcedurePriority": "url"
}