全部产品
Search
文档中心

ID Verification:eKYC_MIN

更新时间:Sep 09, 2025

本文介绍通过纯服务端(API)接入ID Verification的流程。

接口说明

  • 接口名:EkycVerify

  • 请求方法:HTTPS POST

  • 接口说明:通过传入图片资料等信息进行eKYC认证。

  • QPS限量:API独享QPS限量,详情请参见ID Verification服务端API QPS限量说明

  • 服务地址:

    说明

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

    中国香港

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

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

在线调试和集成

说明

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

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

传入图片格式要求

  • 图片格式:JPG、JPEG、PNG。

  • 图片大小:推荐50~100 KB,最大不超过1 MB。

  • 图片分辨率:不超过1920*1080(高*宽),至少为640*480(高*宽),推荐短边缩放到720像素,压缩率大于0.9。照片高大于宽,如果传入的照片宽大于高,可能会影响检测效果。

    说明

    图片转base64格式后,通常会导致数据体积增加。如您需要使用base64格式传参,请保证原始图片的体积不超过0.6MB,以满足1MB的最大数据传输限制。

  • 图片质量建议:

    • 人脸面部需要完整清晰无遮挡,正对摄像头,推荐通过前置摄像头采集的人脸图片。

    • 人脸大小占比图片中面积需要>60%,若人脸较小会影响检测的准确性。

    • 若图片中存在多个人脸,算法默认截取较大的人脸,建议避免传入多人脸图片。

请求参数

名称

类型

是否必选

描述

示例值

ProductCode

String

要接入的产品方案。取值eKYC_MIN

eKYC_MIN

SceneCode

String

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

1234567890

MerchantBizId

String

自定义的业务唯一标识,用于后续定位排查问题使用。支持长度为32位的字母和数字的组合,请确保唯一。

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

您自定义的用户ID,或者其他可以识别特定用户的标识,例如手机号码、邮箱地址等。强烈建议对该字段的值进行预先脱敏,例如对值进行哈希处理。

Y

DocType

String

证件类型,以8位数字组合作为唯一标识。更多说明,请参见证件类型列表

01000000

DocName

String

用户的真实姓名。

说明

当Authorize=T且证件类型为中国内地居民身份证时,以下证件关键信息与证件图片必须输入至少一组:

  • DocName与DocNo。

  • IdOcrPictureBase64或IdOcrPictureUrl。

张三

DocNo

String

用户的证件号码。

说明

当Authorize=T且证件类型为中国内地居民身份证时,以下证件关键信息与证件图片必须输入至少一组:

  • DocName与DocNo。

  • IdOcrPictureBase64或IdOcrPictureUrl。

411xxxxxxxxxxx0001

IdOcrPictureBase64

String

说明

IdOcrPictureBase64和IdOcrPictureUrl二选一。

证件图片Base64编码。

说明

如果您选择该方式传入证件图片,请检查照片大小,不要传入过大的照片。

base64编码

IdOcrPictureUrl

String

证件图片地址,公网可访问的HTTP、HTTPS链接。

https://***

FacePictureBase64

String

说明

FacePictureBase64和FacePictureUrl二选一。

人像图片Base64编码。

说明

如果您选择该方式传入证件图片,请检查照片大小,不要传入过大的照片。

base64编码

FacePictureUrl

String

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

https://***

Crop

String

是否允许裁剪人脸图片:

  • T:允许剪裁

  • F:不允许剪裁(默认)

F

Authorize

String

是否开启官方数据库身份核验:

  • T:开启

  • F:关闭(默认)

说明

目前仅适用于中国内地第二代居民身份证。

F

IdThreshold

String

自定义OCR质量检测阈值模式:

  • 0:标准模式

  • 1:严格模式

  • 2:宽松模式

  • 3(默认):关闭质量检测

0

证件类型列表

DocType

对应证件

01000000

全球护照

00000006

香港居民身份证(2003版)

00000008

香港居民身份证(2018版)

00000007

往来港澳通行证

00000009

港澳居民来往内地通行证

000000011

澳门身份证

000000012

台湾居民来往大陆通行证

00000001

中国内地第二代居民身份证

返回数据

名称

类型

描述

示例值

HTTP Status Code

Integer

HTTP状态码。

200

HTTP Body

RequestId

String

请求ID。

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

Code

String

返回Code

Success

Message

String

返回Code的详细描述。

success

Result.Passed

String

认证最终结果,取值:

  • Y:通过

  • N:不通过

Y

Result.SubCode

String

认证结果描述。更多信息,请参见ResultObject.SubCode错误码说明

200

Result.ExtFaceInfo

String

活体人脸验证相关结果信息。关于JSON格式,请参见右侧示例。更多信息,请参见ExtFaceInfo

{
  "faceAttack": "N",
  "faceComparisonScore": 52.57,
  "facePassed": "N",
  "authorityComparisonScore": 80.39
}

Result.ExtIdInfo

String

证件识别相关结果信息。

关于JSON格式,请参见右侧示例。更多信息,请参见ExtIdInfo

{
  "ocrIdInfo": {
    "expiryDate": "",
    "originOfIssue": "公安部出入境管理局",
    "englishName": "LI SI",
    "sex": "男",
    "name": "李四",
    "idNumber": "H11111112",
    "issueDate": "2013-01-02",
    "birthDate": "1990-02-21"
  },
  "ocrIdPassed": "N",
  "spoofInfo": {
    "spoofResult": "Y",
    "spoofType": [
      "SCREEN_REMARK"
    ]
  }
}

返回Code

HTTP状态码

Code

Message说明

200

Success

请求成功。

400

MissingParameter

参数不能为空。

InvalidParameter

非法参数。

401

UnqualifiedPhoto

传入的图片不可读,或图片分辨率不符合要求,建议更换图片。

需确保照片清晰、曝光正常,完整无遮挡,角度无太大偏差。

DataDuplication

同时传入Base64编码的图片和Url图片地址,此二参数任选其一即可。

ToolargeImage

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

DownloadTimeout

URL图片下载超时。

NoFaceDetected

传入图片无人脸。

403

Forbidden.RAMUserAccessDenied

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

Forbidden.AccountAccessDenied

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

Throttling.Api

API限流拦截。

500

InternalError

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

​ResultObject.SubCode错误码说明

错误码

是否计费

描述和原因建议

200

Yes

认证通过。

201

Yes

官方数据库中姓名和身份证不一致。可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。

202

Yes

官方数据库查询不到身份信息。建议预留人工审核入口,进行人工审核。

203

Yes

查询不到照片或照片不可用。可能原因:权威比对源未留存底库照片。建议预留人工审核入口,进行人工审核。

204

Yes

人脸比对不一致。可能不是同一人或活体照片质量较低。

205

Yes

活体检测存在风险。

207

Yes

上传人脸与官方数据库中的人脸比对不一致。可能不是同一人或人脸照片质量较低。

209

Yes

权威比对源异常。

212

Yes

证件防伪检测存在风险。可能存在翻拍、篡改、复印等高风险操作。

ExtFaceInfo

名称

类型

描述

示例值

facePassed

String

扫脸阶段的活体人脸验证最终结果:

  • Y:通过

  • N:不通过

Y

faceComparisonScore

Double

采集人脸和证件人像比对分。比对分取值范围0~100。

99.99

faceAttack

String

采集人脸是否涉及活体攻击:

  • Y:涉及攻击

  • N:不涉及

N

authorityComparisonScore

Double

采集人脸和官方权威数据源比对分。比对分取值范围0~100。

99.99

ExtIdInfo

名称

类型

描述

示例值

idPassed

String

证件OCR识别阶段的最终结果:

  • Y:通过

  • N:不通过

N

ocrIdInfo

String

证件OCR字段信息。

说明

如果证件OCR流程失败,则该字段值为空。

{
  "expiryDate": "",
  "originOfIssue": "公安部出入境管理局",
  "englishName": "LI SI",
  "sex": "男",
  "name": "李四",
  "idNumber": "H11111112",
  "issueDate": "2013-01-02",
  "birthDate": "1990-02-21"
}

spoofInfo

String

证件防伪检测结果,包括风险判定结果和风险类型:

  • spoofResult:

    • Y存在风险

    • N正常

  • spoofType:

    • SCREEN_REMARK翻拍

    • PHOTO_COPY复印件

    • TAMPER:PS篡改

{
 "spoofResult": "Y",
 "spoofType": ["SCREEN_REMARK"]
}