FACE_IDU_Initialize - ID Verification

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

接口信息

接口名：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 端的表现亦有少量区别。具体功能支持情况，请以接入文档的说明为准。
自动注册枚举值AutoRegistration的逻辑与常规布尔值相反，其中0表示开启，1表示关闭，接入时需注意区分以避免配置错误。
商户用户ID（MerchantUserId）需与业务用户保持稳定的映射关系，且在人脸入库场景中必须满足唯一性约束，若该ID重复将导致人脸注册失败。
当已存在用户更新配置UpdateFaceIfUserExists设为Y时，若MerchantUserId已存在，系统将使用新图片覆盖该用户下原有的人脸数据以完成注册入库。

请求参数

请求字段说明

App SDK与Web SDK的服务端初始化入口统一为InitializeV2，且产品码统一为FACE_IDU。两端共用FACE_IDU的三种核验模式、人脸库、目标人脸及自动注册参数，而端侧差异主要集中在活体交互配置、Web页面配置及返回字段。

集成方式	适用场景	初始化接口返回	请求参数
App SDK	Android / iOS 原生 App 内完成认证	`TransactionId`、`Protocol`	共有参数 + App 特有参数
Web SDK	移动端 H5 、App 内嵌 H5或 PC 浏览器认证	`TransactionId`、`TransactionUrl`、`Protocol`	共有参数 + Web SDK特有参数

字段归类如下：

共有基础参数：两种集成方式均可传入。
App 特有：用于自定义活体动作流程。
Web SDK 特有：用于页面回跳、语言 / UI 与 H5 降级行为控制。

三种核验模式

核验模式	VerifyModel 值	核心逻辑	适用场景	关键输入参数	触发自动注册入库条件
验证模式（默认）	`1`	活体检测 + 1:1 核验	登录、账号找回、敏感操作确认	`TargetFacePicture`、`TargetFacePictureUrl`或 `TargetFacePictureFile`（三选一传入目标人脸）	不适用
检索模式	`0`	活体检测 + 1:N 检索	新用户注册防重、一人一号管控	`FaceGroupCodes`（指定检索人脸库）； `ReturnFaces`（可选，配置匹配阈值以上的返回人脸数量）	活体检测通过，且 1:N 检索未命中
综合模式	`2`	活体检测 + 1:1 核验 + 1:N 检索	新增用户注册（需同时确认本人身份并查重）	需同时传入验证模式（值为 1）与检索模式（值为 0）所需的全部关键参数	活体检测通过、1:1 核验通过，且 1:N 检索未命中

请求参数（共有）

名称	类型	是否必选	描述	示例值
ProductCode	String	是	产品方案标识，固定取值：FACE_IDU。	FACE_IDU
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
VerifyModel	String	否	【产品方案配置】核验模式： `1`验证模式：1:1核验（默认） `0`检索模式：1:N检索 `2`综合模式：1:1核验+1:N检索	0
TargetFacePicture	String	VerifyModel=1或2时必选，三种上传方式任选其一。	【产品方案配置-1:1核验】1:1 比对的可信目标人脸照片Base64编码。	base64
TargetFacePictureUrl	String		【产品方案配置-1:1核验】人像图片地址，公网可访问的HTTP、HTTPS链接。	https://***face1.jpeg
TargetFacePictureFile	InputStream		【产品方案配置-1:1核验】人像图片文件流。	具体接入方式，请参见特殊场景：文件上传 Advance 接口配置。
FaceGroupCodes	String	VerifyModel=0或2时必选	【产品方案配置-1:N检索】1:N 检索的人脸库编码。通过ID Verification产品控制台创建人脸库时获取对应编码，最大支持同时查询10个人脸库。当传入多个人脸库编码时，以逗号区分。	sg***xta，s***uk3j
ReturnFaces	String	VerifyModel=0或2时可选	【产品方案配置-1:N检索】多张人脸超过匹配阈值时返回的匹配人脸数量，默认返回1，最大支持5。	1
AutoRegistration	String	VerifyModel=0或2时可选	【产品方案配置-1:N检索】认证通过后是否自动注册至人脸库： 0：自动注册 1：不注册（默认）	0
FaceRegisterGroupCode	String	VerifyModel=0或2，且AutoRegistration=0时必选	【产品方案配置-1:N检索】自动注册入库的目标人脸库编码。	sg*****xta
UpdateFaceIfUserExists	String	VerifyModel=0或2时可选	【产品方案配置-1:N检索】自动注册入库时若 `MerchantUserId` 已存在，是否使用本次人脸覆盖原有人脸： Y：覆盖 N：不覆盖（默认），并返回 UserId 已存在	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 1:1 验证模式

最小请求示例

VerifyModel 参数设置为 1 ，仅执行活体检测及目标人脸 1:1 比对，不执行人脸库检索，亦不触发自动注册流程。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"android\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "1",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "login_check_01",
  "MerchantBizId": "biz_20230805123456789",
  "MetaInfo": "{\"deviceType\":\"android\",\"osVersion\":\"Android 12\",\"deviceModel\":\"Pixel 6\"}",
  "MerchantUserId": "user_hash_value_123",
  "CallbackUrl": "https://www.example.com/callback",
  "SecurityLevel": "02",
  "Model": "PHOTINUS_LIVENESS",
  "DocVideo": "N",
  "VerifyModel": "1",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "AppQualityCheck": "Y",
  "ShowGuidePage": "1"
}

Web SDK 1:1 验证模式

最小请求示例

VerifyModel 参数设置为 1 ，仅执行活体检测及目标人脸 1:1 比对，不执行人脸库检索，亦不触发自动注册流程。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "1",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "ReturnUrl": "https://example.com/face-idu/result"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "web_login_01",
  "MerchantBizId": "biz_20230805987654321",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_456",
  "CallbackUrl": "https://www.example.com/callback",
  "ReturnUrl": "https://example.com/face-idu/result",
  "SecurityLevel": "02",
  "Model": "LIVENESS",
  "VerifyModel": "1",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "ShowGuidePage": "1",
  "ProcedurePriority": "url"
}

App SDK 1:N 检索模式

最小请求示例

VerifyModel 参数设置为 0，执行活体检测并在指定人脸库中进行 1:N 检索。最小请求时默认不自动注册，因此不传 AutoRegistration 和 FaceRegisterGroupCode。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"android\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "0",
  "FaceGroupCodes": "sg*****xta"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "new_user_reg_01",
  "MerchantBizId": "biz_20230805abcdefg",
  "MetaInfo": "{\"deviceType\":\"android\",\"osVersion\":\"Android 11\"}",
  "MerchantUserId": "user_hash_value_789",
  "SecurityLevel": "02",
  "Model": "SILENT",
  "VerifyModel": "0",
  "FaceGroupCodes": "sg*****xta,sg*****uk3j",
  "ReturnFaces": "3",
  "AutoRegistration": "0",
  "FaceRegisterGroupCode": "sg*****xta",
  "UpdateFaceIfUserExists": "N",
  "AppQualityCheck": "Y",
  "ShowGuidePage": "1"
}

Web SDK 1:N 检索模式

最小请求示例

VerifyModel 参数设置为 0，执行活体检测并在指定人脸库中进行 1:N 检索。最小请求时默认不自动注册，因此不传 AutoRegistration 和 FaceRegisterGroupCode。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "0",
  "FaceGroupCodes": "sg*****xta",
  "ReturnUrl": "https://example.com/face-idu/result"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "web_reg_01",
  "MerchantBizId": "biz_20230805hijklmn",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_000",
  "ReturnUrl": "https://example.com/face-idu/result",
  "SecurityLevel": "02",
  "Model": "LIVENESS",
  "VerifyModel": "0",
  "FaceGroupCodes": "sg*****xta",
  "AutoRegistration": "0",
  "FaceRegisterGroupCode": "sg*****xta",
  "ShowGuidePage": "1"
}

App SDK 综合模式（1:1 + 1:N）

最小请求示例

VerifyModel 参数设置为 2，同时执行目标人脸 1:1 比对和指定人脸库 1:N 检索。最小请求时默认不自动注册。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"ios\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "2",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "FaceGroupCodes": "sg*****xta"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "app_comprehensive_01",
  "MerchantBizId": "biz_20230805opqrst",
  "MetaInfo": "{\"deviceType\":\"ios\",\"osVersion\":\"iOS 15.0\",\"deviceModel\":\"iPhone 13\"}",
  "MerchantUserId": "user_hash_value_111",
  "SecurityLevel": "02",
  "Model": "PHOTINUS_LIVENESS",
  "VerifyModel": "2",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "FaceGroupCodes": "sg*****xta",
  "AutoRegistration": "0",
  "FaceRegisterGroupCode": "sg*****xta",
  "AppQualityCheck": "Y",
  "ShowGuidePage": "1"
}

Web SDK 综合模式（1:1 + 1:N）

最小请求示例

VerifyModel 参数设置为 2，同时执行目标人脸 1:1 比对和指定人脸库 1:N 检索。最小请求时默认不自动注册。

{
  "ProductCode": "FACE_IDU",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "VerifyModel": "2",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "FaceGroupCodes": "sg*****xta",
  "ReturnUrl": "https://example.com/face-idu/result"
}

完整请求示例

{
  "ProductCode": "FACE_IDU",
  "SceneCode": "web_comprehensive_01",
  "MerchantBizId": "biz_20230805uvwxyz",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_222",
  "ReturnUrl": "https://example.com/face-idu/result",
  "SecurityLevel": "02",
  "Model": "LIVENESS",
  "VerifyModel": "2",
  "TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
  "FaceGroupCodes": "sg*****xta",
  "AutoRegistration": "0",
  "FaceRegisterGroupCode": "sg*****xta",
  "ShowGuidePage": "1"
}

接口信息

新加坡

印度尼西亚

中国香港

马来西亚（吉隆坡）

在线调试和集成

接入注意事项

请求参数

请求字段说明

三种核验模式

请求参数（共有）

请求参数（App 接入特有）

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

返回数据

返回字段差异说明

请求示例

App SDK 1:1 验证模式

最小请求示例

完整请求示例

Web SDK 1:1 验证模式

最小请求示例

完整请求示例

App SDK 1:N 检索模式

最小请求示例

完整请求示例

Web SDK 1:N 检索模式

最小请求示例

完整请求示例

App SDK 综合模式（1:1 + 1:N）

最小请求示例

完整请求示例

Web SDK 综合模式（1:1 + 1:N）

最小请求示例

完整请求示例