文档中心

纯API接入(三要素)

最近更新时间：2024.05.07 11:54:12

首次发布时间：2024.03.01 11:57:35

接口简介

身份认证（有源认证）纯API接入，不调用活体检测、ocr等算法能力，只上传姓名、身份证号、人脸图信息，直接请求数据源验证是否为本人

限制条件

无

请求说明

名称	内容
接口地址	https://visual.volcengineapi.com
请求方式	POST
Content-Type	application/json

请求参数
（1）header请求参数
公共请求参数

名称	类型	是否必填	示例值	描述
X-Date	String	是	20201103T104027Z	使用UTC标准时间，日期精确到秒，格式：YYYYMMDD'T'HHMMSS'Z'。
Authorization	String	是	HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}	HMAC-SHA256：签名方法 Credential：签名凭证，其中， -AccessKeyId是访问密钥ID，可在访问密钥（Access Key）获取； -ShortDate是请求的短时间，使用UTC时间，精确到日。请使用格式：YYYYMMDD，例如：20180201 -Region默认为cn-north-1 -Service默认为cv SignedHeaders是参与签名计算的头部信息，content-type 和 host 为必选头部 Signature是签名，可在签名方法获取。注：我们提供了SDK及签名示例供您实现服务快速接入，具体可参考快速接入
X-Security-Token	String	否	无	指安全令牌服务（Security Token Service，STS）颁发的临时安全凭证中的SessionToken： 1.用户 / Service 访问自己的资源则可以使用 AK/SK 直接访问（长期 Token），无需填写该参数。 2.用户 / Service 通过扮演角色去调用接口时需要使用 STS。具体流程：先调用 AssumeRole 获得短期 token, 然后将该 Token 放入该参数去请求目标接口。

（2）Query请求参数
业务请求参数

参数	可选/必选	类型	说明
Action	必选	String	接口名，取值：CertSrcFaceComp
Version	必选	String	版本号，取值：2022-08-31

（3）Body请求参数
业务请求参数

字段名	类型	必选/可选	说明	备注
req_key	string	必选	此处请填写`cert_src_face_comp`
idcard_name	string	在有源比对时必选	身份证姓名
idcard_no	string	在有源比对时必选	身份证号
image	string	必选	人脸图	人脸图Base64，不带mime前缀

输出说明

（1）通用输出参数
请参考通用返回字段及错误码
（2）业务输出参数
data 字段说明

字段名	类型	必选/可选	说明
byted_token	string	必选	本次人脸核身的唯一token
result	bool	必选	是否核验通过
source_comp_details	json	必选	认证的分数和阈值
algorithm_base_resp	json	可选	子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详见下方业务错误码子错误码
req_measure_info	bool	可选	计费说明，部分服务异常情况时无法返回。详见下方业务错误码计费说明
client_config	string	必选	客户端配置信息，请直接透传给端上。

source_comp_details说明

字段名	类型	必选/可选	说明	备注
score	float64	必选	有源比对分数
thresholds	json	必选	有源比对分数阈值

thresholds说明

字段名	类型	必选/可选	说明	备注
1e-3	float64	必选	0.1%置信度阈值
1e-4	float64	必选	0.01%置信度阈值	此值为判断是否通过的标准
1e-5	float64	必选	0.001%置信度阈值
1e-6	float64	必选	0.0001%置信度阈值

（3）输出示例

{
  "code": 10000,
  "data": {
    "algorithm_base_resp": {
      "status_code": 0,
      "status_message": "SUCCESS"
    },
    "binary_data_base64": [],
    "byted_token": "20230402111924116A47A3C09337C67B64",
    "req_measure_info": {
      "measure_type": "query_num",
      "value": 1
    },
    "result": true,
    "source_comp_details": {
      "score": 92.709,
      "thresholds": {
        "1e-3": 60,
        "1e-4": 70,
        "1e-5": 80,
        "1e-6": 90
      }
    }
  },
  "message": "Success",
  "request_id": "20230402111924116A47A3C09337C67B64",
  "status": 10000,
  "time_elapsed": "269.784086ms"
}

错误码

通用错误码

请参考通用返回字段及错误码

业务错误码

子错误码及计费说明

此处列举了algorithm_base_resp的字段结构和不同取值含义，同时也标注了哪些错误码会被实际计费。
对于计费，如果不关注细节，也可以直接参考req_measure_info字段查看计费信息。
字段结构

字段名	类型	必选/可选	说明	备注
algorithm_base_resp	json	必选	子错误说明。

algorithm_base_resp

字段名	类型	必选/可选	说明	备注
status_code	int	必选	子错误码
status_message	string	必选	子错误描述

子错误码

错误码(code)	认证子错误码(algorithm_base_resp)	认证子错误说明	是否计费
10000	0	认证一致	是
50500	100000	服务内部错误
50501	100001	数据源内部错误
50201	201201	缺少输入参数或输入参数为空
50200	201202	输入参数不合法
50206	201301	输入图片为空
50207	201302	输入图片解码失败
50207	201304	输入图片无法处理
60102	203101	输入图片未检测到人脸
50215	210101	输入认证字段不合格（空、不合法等）
50215	210102	输入认证字段查询不到结果
50215	210103	输入认证字段触发源头限流
50215	210104	输入认证字段不匹配	是
50215	210201	身份证号为空
50215	210202	身份证号无效或不符合规范
50215	210203	姓名为空
50215	210204	姓名不符合规则
50215	210205	身份证查询无结果
50215	210206	姓名不匹配	是
50215	210207	认证不一致，姓名与身份证号不匹配
50215	210301	人脸图格式不支持	是
50215	210302	人脸图质量不合格/已损坏	是
50215	210303	人脸图大小过小	是
50215	210304	人脸图为空
50215	210305	人脸图中未检测到人脸
50215	210306	人脸图中存在多个人脸
50215	210307	人脸图特征提取失败
50215	210308	数据源库中的底图质量不合格	是
50215	210309	数据源库中无该身份信息对应的底图	是
50215	210310	人脸图尺寸过大
50215	210311	人脸图不匹配	是
50215	210313	认证不一致，疑似本人	是

计费(req_measure_info)说明

标识此请求是否计费。
字段结构

字段名	类型	必选/可选	说明	备注
req_measure_info	json	必选	计费说明。

req_measure_info

字段名	类型	必选/可选	说明	备注
measure_type	string	必选	取值固定为"query_num"
value	int	必选	取值为0或1。0为不计费，1为计费。