概述
欢迎使用人脸核验API系统。本系统提供标准HTTP API接口，支持第三方业务渠道快速接入人脸实名认证能力。
接口地址
https://您的域名/api/v1/...
数据格式
所有请求和响应均采用 JSON 格式，编码为 UTF-8。支持 JSON Body 和 FormData 两种请求方式。
通用响应格式
{
"code": 0, // 业务状态码，0为成功
"msg": "success", // 提示信息
"data": {...}, // 业务数据
"time": 1717000000
}
认证方式
所有API请求需通过 API Key 进行身份认证。API Key 可在 控制台→用户中心 获取。
方式一：请求头（推荐）
X-Api-Key: your_api_key_here
方式二：URL 参数
?apikey=your_api_key_here
方式三：POST 参数 / JSON Body
apikey=your_api_key_here&name=张三...
方式四：Authorization Bearer
Authorization: Bearer your_api_key_here
未携带或API Key无效时返回 401 或 403。
1. 提交人脸核验
提交用户姓名和身份证号，返回核验链接。将链接提供给用户完成人脸扫描，通过查询接口获取结果。
POST
/api/v1/face/normal/submit.php
提交普通核验
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| name | string | 是 | 用户姓名，如：张三 |
| idcard | string | 是 | 身份证号码，18位 |
| source | string | 否 | 来源标识：api/sdk/console，默认api |
请求示例
POST /api/v1/face/normal/submit.php
X-Api-Key: your_api_key
{
"name": "张三",
"idcard": "110101199001011234"
}
成功响应
{
"code": 0,
"data": {
"token": "a1b2c3...", // 核验令牌，用于查询结果
"url": "https://face.ojwyun.cn/face?token=...", // 核验链接
"call_id": "1" // 调用记录ID
},
"time": 1717000000
}
对接流程：您需要将返回的 url 嵌入到您的应用中（如生成二维码、iframe嵌入或直接跳转），让用户完成人脸扫描。用户完成后通过 token 调用查询接口获取核验结果。
2. 查询核验结果
用户完成人脸扫描后查询核验结果。建议轮询间隔不低于5秒。
GET
/api/v1/face/normal/query.php
查询核验结果
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| token | string | 是 | submit接口返回的核验令牌 |
请求示例
GET /api/v1/face/normal/query.php?token=a1b2c3...&apikey=your_api_key
成功响应（核验通过）
{
"code": 0,
"data": {
"token": "a1b2c3...",
"name": "张三",
"idcard": "110101********1234",
"status": "1", // 1=成功 2=失败
"remark": "核验通过"
}
}
3. 提交权威核验
高级核验方式，支持活体检测（眨眼、摇头、远近等），安全性更高，适用于金融等强实名场景。
POST
/api/v1/face/authority/submit.php
提交权威核验
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| name | string | 是 | 用户姓名 |
| idcard | string | 是 | 身份证号码 |
| returnurl | string | 否 | 核验完成后跳转回您页面的地址 |
| notifyurl | string | 否 | 核验结果回调通知地址 |
| pageTitle | string | 否 | 核验页面标题，默认"实人认证" |
| livingType | string | 否 | 活体检测类型，默认26（综合检测） |
| source | string | 否 | 来源标识：api/sdk/console，默认api |
请求示例
POST /api/v1/face/authority/submit.php
X-Api-Key: your_api_key
{
"name": "张三",
"idcard": "110101199001011234",
"returnurl": "https://yourdomain.com/callback"
}
成功响应
{
"code": 0,
"data": {
"token": "a1b2c3...",
"url": "https://face.ojwyun.cn/face?token=...",
"call_id": "2"
}
}
4. 查询权威核验结果
GET
/api/v1/face/authority/query.php
查询权威核验结果
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| token | string | 是 | submit接口返回的核验令牌 |
请求示例
GET /api/v1/face/authority/query.php?token=a1b2c3...
成功响应
{
"code": 0,
"data": {
"token": "a1b2c3...",
"name": "张三",
"idcard": "110101********1234",
"success": true,
"result": {"code": "200", "message": "核验通过"}
}
}
5. 查询用户信息
查询当前 API Key 对应的账户信息，包括余额、今日调用量、各核验方式剩余额度等。
GET
/api/v1/user/info.php
查询账户信息
请求参数
无业务参数，仅需携带 API Key 认证。
成功响应
{
"code": 0,
"data": {
"balance": 100.00, // 账户余额（元）
"today_total_calls": 5,
"today_success": 3,
"last_api_call_at": "2026-06-05 12:00:00",
"quotas": [
{
"method_code": "face1000",
"method_name": "人脸核验",
"remaining_quota": 450,
"total_purchased": 500
}
]
}
}
错误码说明
| code | HTTP状态码 | 说明 | 处理方式 |
|---|
| 0 | 200 | 成功 | - |
| 1 | 200 | 业务错误 | 根据 msg 提示处理 |
| 401 | 401 | 缺少API密钥 | 检查请求头或参数中是否携带 API Key |
| 403 | 403 | API密钥无效或账号封禁 | 检查 API Key 是否正确，联系管理员 |
| 429 | 429 | 请求频率超限 | 降低请求频率，默认60次/分钟 |
调用示例
cURL
curl -X POST https://your.domain/api/v1/face/normal/submit.php \
-H "X-Api-Key: your_api_key" \
-d "name=张三" \
-d "idcard=110101199001011234"
PHP
$ch = curl_init('https://your.domain/api/v1/face/normal/submit.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['X-Api-Key: your_api_key'],
CURLOPT_POSTFIELDS => ['name'=>'张三', 'idcard'=>'110101199001011234'],
CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
// $res['data']['url'] => 核验链接
// $res['data']['token'] => 核验令牌
JavaScript (fetch)
fetch('https://your.domain/api/v1/face/normal/submit.php', {
method: 'POST',
headers: { 'X-Api-Key': 'your_api_key', 'Content-Type': 'application/json' },
body: JSON.stringify({ name: '张三', idcard: '110101199001011234' })
})
.then(r => r.json())
.then(d => {
// d.data.url => 核验链接
// d.data.token => 核验令牌
});
Python
import requests
url = 'https://your.domain/api/v1/face/normal/submit.php'
headers = { 'X-Api-Key': 'your_api_key' }
data = { 'name': '张三', 'idcard': '110101199001011234' }
res = requests.post(url, headers=headers, data=data).json()
# res['data']['url'] => 核验链接
# res['data']['token'] => 核验令牌
常见问题
Q: 核验流程是怎样的？
A: ① 调用 submit 提交姓名和身份证号 → ② 获取返回的 url 核验链接 → ③ 将链接提供给用户完成人脸扫描 → ④ 通过 query 查询结果。
Q: 核验链接有效期多久？
A: 30分钟，超时后需重新发起核验。
Q: 如何获取 API Key？
A: 登录 控制台 → 用户中心 → API密钥。
Q: 如何购买额度？
A: 登录控制台选择套餐购买，或余额充值按次扣费。
Q: 支持哪些核验方式？
A: 普通人脸核验（快速核验）和 权威人脸核验（含活体检测，安全性更高）。
Q: 请求频率限制是多少？
A: 默认60次/分钟，有更高需求请联系管理员。