You need to enable JavaScript to run this app.
导航
TokenPro接口
最近更新时间:2025.03.24 14:55:13首次发布时间:2023.04.10 16:53:06
我的收藏
有用
有用
无用
无用

接口简介

业务已存有用户资料的情况下,可以通过服务端直接调用Token接口将用户资料进行上传,不进行端上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

接口名,取值:CertToken

Version

必选

String

版本号,取值:2022-08-31

(3)Body请求参数
业务请求参数

字段名

类型

必选/可选

说明

备注

req_key

string

必选

此处请填写cert_pro_token

sts_token

string

必选

通过STS接口获取的临时token

tos_info

json

可选

客户TOS信息,在需要将认证数据存储到客户TOS时必传

ref_source

string

必选

比对类型

可选类型:
0:无源比对
1:有源比对

idcard_name

string

在有源比对时必选

身份证姓名

idcard_no

string

在有源比对时必选

身份证号

ref_image

string

在无源比对时必选

输入图片的base64数组,在无源比对时需要传入1张用户的基准图,有源比对无需传入

liveness_timeout

int

可选

端上活体超时时长

可选范围: [5, 60],默认:10

max_liveness_trial

int

可选

端上活体最大尝试次数

可选范围:[1, 100],默认:10

risk_liveness_type

json

可选

依据风险等级的活体类型,下文会详细解释其结构

risk_motion_count

json

可选

依据风险等级下发的动作数量,下文会详细解释其结构

risk_motion_list

json

可选

依据风险等级的可下发动作列表,下文会详细解释其结构

risk_fixed_motion_list

json

可选

依据风险等级的固定要下发的动作列表,下文会详细解释其结构

callback_info

json

可选

回调配置信息

config_id

string

可选

固定配置ID,固定配置的说明与使用方式请参考Config接口

tos_info说明

字段名

类型

必选/可选

说明

备注

sts_ak

string

必选

客户通过STS接口获取的临时AK,在需要将认证数据存储到客户TOS时必传

sts_sk

string

必选

客户通过STS接口获取的临时SK,在需要将认证数据存储到客户TOS时必传

sts_token

string

必选

客户通过STS接口获取的临时Token,在需要将认证数据存储到客户TOS时必传

bucket

string

必选

TOS Bucket

endpoint

string

必选

TOS Endpoint

region

string

必选

TOS Region

risk_liveness_type说明

字段名

类型

必选/可选

说明

备注

free

string

必选

设备无风险时的动作类型

默认motion,可选类型:
motion(默认):动作活体
reflection:炫彩活体(仅在使用SDK时生效)
still:静默活体(仅在使用SDK时生效)

low

string

必选

设备低风险时的动作类型

默认motion,可选类型同上

medium

string

必选

设备中风险时的动作类型

默认motion,可选类型同上

high

string

必选

设备高风险时的动作类型

默认reflection,可选类型同上

risk_motion_count说明

字段名

类型

必选/可选

说明

备注

free

int

必选

设备无风险时下发动作数量

默认2,可选范围:[1, 4]

low

int

必选

设备低风险时下发动作数量

默认2,可选范围同上

medium

int

必选

设备中风险时下发动作数量

默认3,可选范围同上

high

int

必选

设备高风险时下发动作数量

默认4,可选范围同上

risk_motion_list说明

字段名

类型

必选/可选

说明

备注

free

array of string

必选

设备无风险时可下发动作列表

默认全部可下发,可选动作:
0:眨眼
1:张嘴
2:点头
3:摇头

low

array of string

必选

设备低风险时可下发动作列表

默认全部可下发,可选值同上

medium

array of string

必选

设备中风险时可下发动作列表

默认全部可下发,可选值同上

high

array of string

必选

设备高风险时可下发动作列表

默认全部可下发,可选值同上

risk_fixed_motion_list说明

字段名

类型

必选/可选

说明

备注

free

array of string

必选

设备无风险时固定下发的动作列表

默认为空,可选动作同risk_motion_list中动作

low

array of string

必选

设备低风险时固定下发的动作列表

默认为空,可选值同上

medium

array of string

必选

设备中风险时固定下发的动作列表

默认为空,可选值同上

high

array of string

必选

设备高风险时固定下发的动作列表

默认为空,可选值同上

callback_info说明

字段名

类型

必选/可选

说明

备注

switch

bool

必选

如需主动推送结果的回调,请填入true

默认false

block

bool

必选

如需阻塞式回调,请填入true

默认false

url

string

必选

回调的目标位置

默认为空串,且仅当非空串时才尝试回调

client_name

string

必选

回调接收客户的唯一代号,用于回调信息的加密

使用回调功能的接入方必须注册,获取代号以及对应的秘钥

Body示例
以下为body示例,已脱去敏感参数

{
  "req_key": "cert_pro_token",
  "sts_token": "1681108476",
  "ref_source": "0",
  "ref_image": "/9jxxxxxxxxxxxxx",
  "risk_motion_count": {
    "free": 3,
    "low": 3,
    "medium": 1,
    "high": 2
  },
  "risk_liveness_type": {
    "free": "motion",
    "low": "motion",
    "medium": "motion",
    "high": "reflection"
  },
  "risk_motion_list": {
    "free": [
      "1",
      "2",
      "3"
    ],
    "low": [
      "1",
      "2",
      "3"
    ],
    "medium": [
      "0"
    ],
    "high": [
      "1",
      "3"
    ]
  },
  "risk_fixed_motion_list": {
    "free": [
      "1",
      "2",
      "3"
    ],
    "low": [
      "1",
      "2",
      "3"
    ],
    "medium": [
      "0"
    ],
    "high": [
      "1",
      "3"
    ]
  },
  "callback_info": {
     "switch": true,
     "block": false,
     "url": "https://xxx.xxx.xxx/xx",
     "client_name": "abc"
  }
}

回调说明

当回调开关为true时,在callback_info中提供的url会收到HTTP POST的回调信息,为application/json格式,各字段如下,重要字段皆使用AES-CBC对称加密,使用该功能的接入方应联系我们获取唯一秘钥。
回调信息解密:回调报文的body为json编码序列,除了result字段,其余字段均使用AES-CBC对称加密算法,使用的秘钥为128位,秘钥(key)和初始化向量(iv)一致,解密后的数据最后一字节存储了填充字节数,解密后的数据去掉填充字节数为有效部分,取有效部分即为原始json序列,以下python伪代码展示了解密一个字段过程。

from Crypto.Cipher import AES
import base64

# key为秘钥, iv为初始化向量, content为回调HTTP报文的body内容
cipher = AES.new(key, AES.MODE_CBC, iv)
src_cmp_details = json.loads(content)["source_comp_details"]
ciphertext = base64.b64decoding(src_cmp_details)
text = cipher.decrypt(ciphertext)
valid_len = text[-1]
ret = text[:len(text)-valid_len]
# ret为source_comp_details的明文结果

字段名

类型

是否加密

说明

备注

result

bool

认证结果

source_comp_details

json

认证的分数和阈值。详细见:Query接口中的source_comp_details

verify_req_measure_info

json

计费说明,部分服务异常情况时无法返回。详细见:错误码和计费中的req_measure_info

verify_algorithm_base_resp

json

子错误说明,可以进一步区分错误原因,部分服务异常情况时无法返回。详细见错误码和计费中的algorithm_base_resp。

byted_token

string

本次人脸核身的唯一token

输出说明

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

字段名

类型

必选/可选

说明

备注

byted_token

string

必选

本次人脸核身的唯一token

client_config

string

必选

客户端配置信息,请直接透传给端上。

(3)输出示例

{
    "code":10000,
    "data":{
        "byted_token": "",
        "client_config": ""
    },
    "message":"Success",
    "request_id":"6838889517957515275",
    "time_elapsed":"41.897331ms"
}

错误码

(1)通用错误码
请参考通用返回字段及错误码
(2)业务错误码

HttpCode

错误码

错误消息

描述

200

10000

"Success"

成功