千帆信用 API

千帆信用实名认证接口，基于活体检测 + 人脸比对实现同一人核验。

接入流程
1. 服务器端调用【创建认证会话】拿到认证链接；
2. 用户在 H5 页面完成活体检测；
3. 系统自动扣费，并通过回调或查询接口返回结果。

v5.0 变更
• 新增 IP 白名单；
• 支持在线更换 API Key，历史记录自动迁移。

1. 创建认证会话 (Create Auth Session)

服务器端调用，返回认证链接供终端用户跳转。API Key 仅在服务器端使用，不要暴露给前端。

请求方式	POST
接口地址	`face/api.php?action=create_auth`

请求参数

参数名	类型	必填	说明
api_key	String	是	您在后台分配的 API Key
name	String	是	用户真实姓名（需与身份证一致）
id_card	String	是	用户 18 位身份证号码
callback_url	String	否	认证完成后的异步通知地址

返回示例 (JSON)

{
  "success": true,
  "message": "认证成功会话已创建",
  "data": {
    "token": "a1b2c3d4e5f6...",
    "auth_url": "https://gulangvision.cn/face/liveness_check.html?token=a1b2c3d4e5f6...",
    "expire_in": 300
  }
}

代码示例 (PHP)

<?php
// 在服务器端调用 API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gulangvision.cn/face/api.php?action=create_auth');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'name' => '张三',
    'id_card' => '110101199001011234',
    'callback_url' => 'https://gulangvision.cn/callback.php'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    // 重定向用户到认证页面
    header('Location: ' . $result['data']['auth_url']);
} else {
    echo '错误: ' . $result['message'];
}
?>

安全提示 API Key 仅在服务器端使用，不要在前端 JavaScript 中直接调用此接口。

2. 查询认证状态 (Query Status)

未配置回调地址时，可通过此接口主动查询认证状态。

请求方式	GET
接口地址	`face/api.php?action=query_status`

请求参数

参数名	类型	必填	说明
token	String	二选一	认证令牌（从创建会话时获取）
id_card	String	二选一	身份证号

返回示例 (JSON)

{
  "success": true,
  "data": {
    "is_finished": true,
    "name": "张*",
    "id_card": "110***********1234",
    "result_code": 1001,
    "score": 95,
    "result_text": "成功",
    "time": "2026-04-30 12:30:45"
  }
}

3. 异步回调通知 (Callback)

用户完成认证后，系统会向 callback_url 发送 POST 请求。

回调时机
无论成功、存疑还是失败都会回调：
• 成功：result_code = 1001；
• 存疑：result_code = 1002（需人工审核）；
• 失败：result_code 为其他值。

回调参数

参数名	类型	说明
key	String	API Key
token	String	认证令牌
name	String	用户姓名
id_card	String	身份证号
result_code	Integer	1001: 成功, 1002: 存疑, 1003: 失败, 其他: 错误
message	String	结果描述

短信发送 API

支持验证码、通知类短信，模板变量替换。

前置条件
账户需先完成实名认证。
扣费优先级：先扣短信条数额度，不足时扣账户余额。

1. 发送短信 (Send SMS)

调用此接口发送短信，支持模板变量替换。

请求方式	POST
接口地址	`face/smsapi.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
phone	String	是	手机号（11位）
template_id	String	是	短信模板ID（管理员后台创建）
variables	JSON	否	模板变量，JSON格式，例如：{"code":"123456"}

返回示例 (JSON)

{
  "code": 200,
  "msg": "短信发送成功",
  "data": {
    "phone": "138****1234",
    "template_id": "VERIFY_CODE",
    "cost": 0.50,
    "remaining_balance": 99.50,
    "remaining_sms": 9
  }
}

代码示例 (PHP)

<?php
// 发送短信验证码
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gulangvision.cn/face/smsapi.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'phone' => '13800138000',
    'template_id' => 'VERIFY_CODE',
    'variables' => json_encode(['code' => '123456'])
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    echo "发送成功！剩余短信条数: " . $result['data']['remaining_sms'];
} else {
    echo '发送失败: ' . $result['msg'];
}
?>

邮箱发送 API

支持 HTML 邮件，可用 JSON 或表单两种格式请求。

前置条件
账户需先完成实名认证。
扣费优先级：先扣邮箱封数额度，不足时扣账户余额。

1. 发送邮件 (Send Email)

调用此接口发送邮件，支持 HTML 格式。

请求方式	POST
接口地址	`face/mailapi.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
to_email	String	是	收件人邮箱
subject	String	是	邮件主题
content	String	是	邮件内容（支持HTML）
is_html	Boolean	否	是否为HTML格式，默认true

请求格式
• JSON：设置 Content-Type: application/json；
• 表单：使用 http_build_query 或 FormData。

返回示例 (JSON)

{
  "code": 200,
  "msg": "邮件发送成功",
  "data": {
    "to_email": "user@example.com",
    "subject": "验证码通知",
    "cost": 0.30,
    "remaining_balance": 99.20,
    "remaining_email": 19
  }
}

代码示例 - 表单格式 (PHP)

<?php
// 发送HTML邮件（表单格式）
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gulangvision.cn/face/mailapi.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'to_email' => 'user@example.com',
    'subject' => '验证码通知',
    'content' => '<h1>您的验证码是：123456</h1><p>5分钟内有效</p>'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    echo "发送成功！";
} else {
    echo '发送失败: ' . $result['msg'];
}
?>

代码示例 - JSON格式 (PHP)

<?php
// 发送HTML邮件（JSON格式）
$data = [
    'api_key' => 'YOUR_API_KEY',
    'to_email' => 'user@example.com',
    'subject' => '验证码通知',
    'content' => '<h1>您的验证码是：123456</h1><p>5分钟内有效</p>'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gulangvision.cn/face/mailapi.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    echo "发送成功！";
} else {
    echo '发送失败: ' . $result['msg'];
}
?>

代码示例 - JavaScript (Fetch)

<script>
// 发送HTML邮件（JSON格式）
fetch('https://gulangvision.cn/face/mailapi.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: 'YOUR_API_KEY',
        to_email: 'user@example.com',
        subject: '验证码通知',
        content: '<h1>您的验证码是：123456</h1><p>5分钟内有效</p>'
    })
})
.then(res => res.json())
.then(data => {
    if (data.code == 200) {
        console.log('发送成功！');
    } else {
        console.log('发送失败:', data.msg);
    }
});
</script>

计费说明

各服务的扣费规则与默认单价。

1. 扣费优先级

先扣资源包额度（短信条数 / 邮箱封数 / 三要素次数 / 二要素次数 / 芝麻信用次数）；
资源包不足或过期时，从账户余额扣费。

2. 计费标准

每个客户可单独设置各业务单价；未设置时使用后台全局默认价。

服务类型	默认单价	说明
实名认证（人脸）	后台设置	按次计费
三要素认证	后台设置	姓名 + 身份证 + 手机号
二要素认证	后台设置	姓名 + 身份证
芝麻信用认证	后台设置	跳转认证，按次计费
短信发送	后台设置	按条计费
邮箱发送	后台设置	按封计费

3. 扣费示例

示例1：有短信条数额度
账户余额：¥100.00
短信条数：10条
发送1条短信后：
  - 短信条数：9条
  - 账户余额：¥100.00（不变）

示例2：无短信条数额度
账户余额：¥100.00
短信条数：0条
发送1条短信后：
  - 短信条数：0条
  - 账户余额：¥99.50（扣除¥0.50）

4. 实名认证要求

前置条件
短信和邮箱发送功能需先完成实名认证；
未完成实名认证的账户调用发送接口会返回 403 错误。

三要素认证 API

姓名 + 身份证号 + 手机号三要素一致性核验，基于支付宝授权完成。

前置条件
账户需先完成实名认证。
扣费优先级：先扣三要素次数额度，不足时扣账户余额。

1. 发起三要素认证 (Generate)

调用此接口创建三要素认证会话，返回认证链接供用户跳转。

请求方式	GET/POST
接口地址	`face/three_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：generate
name	String	是	用户真实姓名
cert_no	String	是	用户 18 位身份证号码
mobile	String	是	用户手机号

返回示例 (JSON)

{
  "code": 200,
  "msg": "认证链接生成成功",
  "verify_id": "a1b2c3d4e5f6...",
  "auth_url": "https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=...&cert_verify_id=a1b2c3d4e5f6..."
}

代码示例 (PHP)

<?php
// 发起三要素认证
$apiUrl = 'https://gulangvision.cn/face/three_cert/api.php';
$params = [
    'api_key' => 'YOUR_API_KEY',
    'action' => 'generate',
    'name' => '张三',
    'cert_no' => '110101199001011234',
    'mobile' => '13800138000'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    // 重定向用户到支付宝认证页面
    header('Location: ' . $result['auth_url']);
} else {
    echo '错误: ' . $result['msg'];
}
?>

2. 查询认证结果 (Result)

用户完成认证后，调用此接口查询认证结果。

请求方式	GET/POST
接口地址	`face/three_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：result
verify_id	String	是	发起认证时返回的 verify_id

返回示例 (JSON)

{
  "code": 200,
  "msg": "查询成功",
  "passed": "T",
  "is_verify": 1
}

返回参数说明

参数名	类型	说明
passed	String	T: 通过, F: 未通过
is_verify	Int	1: 已认证, 0: 未认证

二要素认证 API

姓名 + 身份证号二要素一致性核验，基于支付宝授权完成。

前置条件
账户需先完成实名认证。
扣费优先级：先扣二要素次数额度，不足时扣账户余额。

1. 发起二要素认证 (Generate)

调用此接口创建二要素认证会话，返回认证链接供用户跳转。

请求方式	GET/POST
接口地址	`face/two_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：generate
name	String	是	用户真实姓名
cert_no	String	是	用户 18 位身份证号码

返回示例 (JSON)

{
  "code": 200,
  "msg": "认证链接生成成功",
  "verify_id": "a1b2c3d4e5f6...",
  "auth_url": "https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=...&cert_verify_id=a1b2c3d4e5f6..."
}

代码示例 (PHP)

<?php
// 发起二要素认证
$apiUrl = 'https://gulangvision.cn/face/two_cert/api.php';
$params = [
    'api_key' => 'YOUR_API_KEY',
    'action' => 'generate',
    'name' => '张三',
    'cert_no' => '110101199001011234'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    // 重定向用户到支付宝认证页面
    header('Location: ' . $result['auth_url']);
} else {
    echo '错误: ' . $result['msg'];
}
?>

2. 查询认证结果 (Result)

用户完成认证后，调用此接口查询认证结果。

请求方式	GET/POST
接口地址	`face/two_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：result
verify_id	String	是	发起认证时返回的 verify_id

返回示例 (JSON)

{
  "code": 200,
  "msg": "查询成功",
  "passed": "T",
  "is_verify": 1
}

返回参数说明

参数名	类型	说明
passed	String	T: 通过, F: 未通过
is_verify	Int	1: 已认证, 0: 未认证

芝麻信用认证 API

基于支付宝官方身份验证服务（009yj3）的跳转式实名认证。调用接口生成认证链接，引导用户跳转至支付宝完成认证后，再查询认证结果。支持四种认证场景，可根据业务需要选择。

前置条件
账户需先完成实名认证。
扣费优先级：先扣芝麻信用认证次数额度，不足时扣账户余额。
认证场景码（biz_code）由平台在后台为每个账户独立配置，默认为 FACE。

认证场景码 biz_code

认证场景码决定认证方式，取值如下：

取值	说明
FACE	多因子人脸认证（默认）
CERT_PHOTO	多因子证照认证
CERT_PHOTO_FACE	多因子证照和人脸认证
SMART_FACE	多因子快捷认证

注：实际可用的场景码取决于平台签约情况，如需更换请联系平台配置。

1. 生成认证链接 (Generate)

调用此接口初始化认证会话，返回认证跳转链接。将用户重定向至返回的 auth_url，用户在支付宝端完成认证后，会跳回平台回调页。

请求方式	GET/POST
接口地址	`face/zhima_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：generate
name	String	是	用户真实姓名
cert_no	String	是	用户 18 位身份证号码
biz_code	String	否	认证场景码，可选值：FACE / CERT_PHOTO / CERT_PHOTO_FACE / SMART_FACE。不传则按账户后台配置的默认场景码
return_url	String	否	用户完成认证后的跳回地址。不传则跳回平台默认回调页

返回示例 (JSON)

{
  "code": 200,
  "msg": "认证链接生成成功",
  "certify_id": "2c9e6xxx...",
  "auth_url": "https://openapi.alipay.com/gateway.do?alipay_sdk=...&certify_id=2c9e6xxx...",
  "biz_code": "FACE"
}

返回参数说明

参数名	类型	说明
certify_id	String	认证会话 ID，查询认证结果时需传入
auth_url	String	支付宝认证跳转地址，将用户重定向至此 URL
biz_code	String	本次认证使用的场景码

扣费说明
认证通过后才扣费，未通过不扣费。扣费时机在调用 query 接口且支付宝返回 passed=T 时，优先扣次数，次数不足扣余额。重复查询不会重复扣费。

代码示例 (PHP)

<?php
// 生成芝麻信用认证链接
$apiUrl = 'https://gulangvision.cn/face/zhima_cert/api.php';
$params = [
    'api_key' => 'YOUR_API_KEY',
    'action'  => 'generate',
    'name'    => '张三',
    'cert_no' => '110101199001011234'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    // 保存 certify_id，用于后续查询
    session_start();
    $_SESSION['zhima_certify_id'] = $result['certify_id'];
    // 重定向用户到支付宝认证页
    header('Location: ' . $result['auth_url']);
    exit;
} else {
    echo '错误: ' . $result['msg'];
}
?>

2. 查询认证结果 (Query)

用户完成认证并跳回平台后，调用此接口查询认证结果。建议在回调页或用户返回后轮询查询（认证状态可能存在短暂延迟，可重试 1-2 次）。

请求方式	GET/POST
接口地址	`face/zhima_cert/api.php`

请求参数

参数名	类型	必填	说明
api_key	String	是	您的 API Key
action	String	是	固定值：query
certify_id	String	是	generate 接口返回的 certify_id

返回示例 (JSON)

{
  "code": 200,
  "msg": "查询成功",
  "passed": "T",
  "result_code": 1001,
  "is_verify": 1
}

返回参数说明

参数名	类型	说明
passed	String	T: 认证通过, F: 认证未通过
result_code	Int	标准化结果码：1001 成功, 1003 失败
is_verify	Int	1: 已认证, 0: 未认证

代码示例 (PHP)

<?php
// 查询芝麻信用认证结果
session_start();
$certifyId = $_SESSION['zhima_certify_id'] ?? '';
if (!$certifyId) {
    echo '未找到认证会话';
    exit;
}

$apiUrl = 'https://gulangvision.cn/face/zhima_cert/api.php';
$params = [
    'api_key'    => 'YOUR_API_KEY',
    'action'     => 'query',
    'certify_id' => $certifyId
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] == 200) {
    if ($result['passed'] === 'T') {
        echo '认证通过';
    } else {
        echo '认证未通过';
    }
} else {
    echo '查询失败: ' . $result['msg'];
}
?>

3. 完整流程时序

商户系统                    本平台API                    支付宝
   |                           |                          |
   |--- generate ------------->|                          |
   |                           |--- 初始化认证 ----------->|
   |                           |<-- certify_id ------------|
   |                           |--- 生成认证链接 ---------->|
   |                           |<-- auth_url --------------|
   |<-- certify_id + auth_url -|                          |
   |                           |                          |
   |--- 302 重定向用户到 auth_url ----------------------->|
   |                           |                          |
   |                           |    用户在支付宝完成认证     |
   |                           |                          |
   |<--- 用户跳回平台回调页 ----------------------------|
   |                           |                          |
   |--- query(certify_id) ---->|                          |
   |                           |--- 查询认证结果 ---------->|
   |                           |<-- passed ---------------|
   |<-- passed / result_code -|                          |

常见错误码

各接口可能返回的错误码及处理方式。

实名认证错误码

错误信息	原因及解决方案
无效的 API Key	Key 不存在，请检查是否正确。
API Key 已被禁用	该 Key 已被管理员封禁。
余额不足	账户余额为 0，请登录后台充值。
操作过于频繁，请稍后再试	同一身份证号 5 秒内只能认证一次。
缺少必要参数	缺少 api_key、name 或 id_card 参数。
无效的认证令牌或已过期	Token 不存在或超过 5 分钟有效期。
该认证已完成	Token 已被使用，每个 Token 只能使用一次。
当前IP未被授权访问	IP不在白名单中，用户设置白名单

三要素 / 二要素认证错误

错误信息	原因及解决方案
passed = F	姓名 / 身份证 / 手机号不一致，请核对后重试。
verify_id 无效或已过期	认证会话超时，需重新发起 generate。
次数不足 / 余额不足	资源包额度耗尽且余额不足，请充值或购买对应次数包。

芝麻信用认证错误

错误信息	原因及解决方案
passed = F	认证未通过，用户在支付宝端未通过核验，可重新发起认证。
缺少 certify_id	查询时未传入 certify_id，需使用 generate 返回的 certify_id。
无权访问此认证记录	certify_id 不属于当前 api_key，请核对。
余额和芝麻信用认证次数都不足	芝麻信用次数额度已用完且账户余额不足，请充值或购买次数包。
身份证号格式不正确	cert_no 需为 18 位标准身份证号。
初始化失败 / 查询失败	支付宝侧返回异常，可稍后重试或联系平台排查。

短信&邮箱错误码

错误码	错误信息	原因及解决方案
403	请先完成实名认证	账户未完成实名认证，请先完成认证。
400	缺少必要参数	缺少 api_key、phone 等必填参数。
400	手机号格式错误	手机号必须是11位数字。
400	邮箱格式错误	邮箱格式不正确。
402	余额和短信条数都不足	请充值或购买短信包。
402	余额和邮箱封数都不足	请充值或购买邮箱包。
429	发送频率过快	同一手机号1分钟内只能发送1次。
500	短信服务暂时不可用	短信网关故障，请稍后重试。
500	邮件发送失败	SMTP配置错误，请联系管理员。

频率限制

限制类型	限制规则	说明
单手机号	1次/分钟	同一手机号1分钟内只能发送1次
单IP	10次/小时	同一IP每小时最多发送10次

使用建议
• 短信验证码建议设置 5 分钟有效期；
• 重要通知同时发短信和邮件更稳妥；
• 定期查看发送记录，留意异常发送；
• 余额和次数包留足余量，避免业务中断。

鼓浪云 开发文档

千帆信用 API

1. 创建认证会话 (Create Auth Session)

请求参数

返回示例 (JSON)

代码示例 (PHP)

2. 查询认证状态 (Query Status)

请求参数

返回示例 (JSON)

3. 异步回调通知 (Callback)

回调参数

短信发送 API

1. 发送短信 (Send SMS)

请求参数

返回示例 (JSON)

代码示例 (PHP)

邮箱发送 API

1. 发送邮件 (Send Email)

请求参数

返回示例 (JSON)

代码示例 - 表单格式 (PHP)

代码示例 - JSON格式 (PHP)

代码示例 - JavaScript (Fetch)

计费说明

1. 扣费优先级

2. 计费标准

3. 扣费示例

4. 实名认证要求

三要素认证 API

1. 发起三要素认证 (Generate)

请求参数

返回示例 (JSON)

代码示例 (PHP)

2. 查询认证结果 (Result)

请求参数

返回示例 (JSON)

返回参数说明

二要素认证 API

1. 发起二要素认证 (Generate)

请求参数

返回示例 (JSON)

代码示例 (PHP)

2. 查询认证结果 (Result)

请求参数

返回示例 (JSON)

返回参数说明

芝麻信用认证 API

认证场景码 biz_code

1. 生成认证链接 (Generate)

请求参数

返回示例 (JSON)

返回参数说明

代码示例 (PHP)

2. 查询认证结果 (Query)

请求参数

返回示例 (JSON)

返回参数说明

代码示例 (PHP)

3. 完整流程时序

常见错误码

实名认证错误码

三要素 / 二要素认证错误

芝麻信用认证错误

短信&邮箱错误码

频率限制

鼓浪云开发文档