证件照合规性检测
检测证件照尺寸、背景、人像构图、姿态与画质等合规项。
接口地址:https://api.zjzapi.com/idphoto/check
请求方式:POST(application/x-www-form-urlencoded)
返回格式:json
接口费用:检测成功扣除0.012元
请求参数:
| 分类 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 基础参数 | key | 是 | string | 应用的key |
| image | 是 | string | base64后的图片内容,大小不超过4M,分辨率不超过3072px。 | |
| 规格参数 | item_id | 否 | int | 规格id,《查看规格列表》 |
| width_px | 否 | int | 证件照宽(px),若提供 item_id 可省略 | |
| height_px | 否 | int | 证件照高(px),若提供 item_id 可省略 | |
| dpi | 否 | int | 图片分辨率,常见300、350,若提供 item_id 可省略 | |
| file_size_min | 否 | int | 最小文件大小(kb),若提供 item_id 可省略 | |
| file_size_max | 否 | int | 最大文件大小(kb),若提供 item_id 可省略 | |
| file_format | 否 | string | 照片格式,仅支持: jpg、jpeg、png | |
| bg_colors | 否 | string | 颜色名称(blue、white、red),支持传多个,格式为:"blue,white",若提供 item_id 可省略 | |
| solid_bg | 否 | int | 纯色背景检测(0/1) | |
| 人像构图 / 位置比例 | face_width_ratio_min | 否 | float | 人脸宽度最小比例(0.01 - 1.0) |
| face_width_ratio_max | 否 | float | 人脸宽度最大比例(0.01 - 1.0) | |
| head_height_ratio_min | 否 | float | 头部高度最小比例(0.01 - 1.0) | |
| head_height_ratio_max | 否 | float | 头部高度最大比例(0.01 - 1.0) | |
| eye_distance_ratio_min | 否 | float | 双眼间距最小比例(0.01 - 1.0) | |
| eye_distance_ratio_max | 否 | float | 双眼间距最大比例(0.01 - 1.0) | |
| head_top_gap_ratio_min | 否 | float | 头顶离上边缘最小比例(0.01 - 1.0) | |
| head_top_gap_ratio_max | 否 | float | 头顶离上边缘最大比例(0.01 - 1.0) | |
| eyes_to_bottom_ratio_min | 否 | float | 眼睛离下边缘最小比例(0.01 - 1.0) | |
| eyes_to_bottom_ratio_max | 否 | float | 眼睛离下边缘最大比例(0.01 - 1.0) | |
| 姿态与完整性 | head_incomplete | 否 | int | 头部缺失检测(0/1) |
| upper_body | 否 | int | 上半身检测(0/1) | |
| shoulder_horizontal | 否 | int | 肩膀水平检测,大于设置值检测不通过,单位倾斜角度,推荐值:5 | |
| face_pose_pitch | 否 | int | 面部姿势俯仰角(低头/抬头),大于设置度数检测不通过,单位倾斜角度,推荐值:15 | |
| face_pose_yaw | 否 | int | 面部姿势偏航角(左/右转头),大于设置度数检测不通过,单位倾斜角度,推荐值:15 | |
| face_pose_roll | 否 | int | 面部姿势滚角(歪头/倾斜),大于设置度数检测不通过,单位倾斜角度,推荐值:15 | |
| 画质与光照 | face_yinyang | 否 | int | 阴阳脸检测,大于设置值检测不通过,计算亮度差,推荐值:60 |
| face_clarity | 否 | float | 面部清晰度,小于设置值最低值检测不通过,评分越高越清晰,推荐值:0.5 | |
| face_brightness | 否 | float | 面部亮度,小于设置值最低值检测不通过,推荐值:0.3 | |
| face_exposure | 否 | float | 面部曝光,大于设置检测不通过,推荐值:0.85 | |
| face_retouch | 否 | int | 美颜精修(0/1) | |
| 遮挡与表情 | hair_shoulder | 否 | int | 头发遮挡肩膀(0/1) |
| hair_eyebrow | 否 | int | 头发遮挡眉毛(0/1) | |
| face_mask | 否 | int | 口罩检测(0/1) | |
| face_block | 否 | int | 面部遮挡(0/1) | |
| face_eye | 否 | int | 眼睛检测(0/1),闭眼或者未直视镜头 | |
| ear | 否 | int | 耳朵检测(0/1),双耳朵检测到才会通过,本身露不出的也会检测通过 | |
| mouth | 否 | int | 张嘴检测(0/1) | |
| 服装与饰品 | shirtless | 否 | int | 着装检测(0/1),光膀子 |
| revealing_clothing | 否 | int | 衣着暴露(0/1),领口大,吊带等 | |
| tint_clothes | 否 | int | 浅色衣服(0/1) | |
| cap | 否 | int | 帽子检测(0/1) | |
| glasses | 否 | int | 眼镜检测(0/1) | |
| earphone | 否 | int | 耳机检测(0/1) | |
| necklace | 否 | int | 项链检测(0/1) | |
| earrings | 否 | int | 耳饰检测(0/1) | |
| headwear | 否 | int | 头饰检测(0/1) |
返回参数:
| 名称 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码(0=成功,-1=错误) |
| msg | string | 错误提示 |
| data | array | 数据集 |
JSON返回示例:
{
"data": {
"passed_status": 0, # 总检测结果,1=通过,0=不通过
"passed_list": [ # 各检测项结果
{
"key": "width_px",
"passed": 0, # 1=通过,0=不通过
"msg": "图片宽度错误", # 检测提示
"detail": { # 检测详情
"unit": "px", # 单位
"actual": 358 # 检测结果值
}
},
{
"key": "height_px",
"passed": 0,
"msg": "图片高度错误",
"detail": {
"unit": "px",
"actual": 441
}
},
{
"key": "dpi",
"passed": 0,
"msg": "图片dpi错误",
"detail": {
"unit": "dpi",
"actual": 0
}
},
{
"key": "file_format",
"passed": 1,
"msg": "",
"detail": {}
},
{
"key": "face_pose_yaw",
"passed": 1,
"msg": "",
"detail": {
"unit": "degree",
"actual": 1.29
}
},
{
"key": "bg_colors",
"passed": 0,
"msg": "背景色错误",
"detail": {}
},
{
"key": "face_clarity",
"passed": 1,
"msg": "",
"detail": {
"unit": "score",
"actual": 0.6
}
}
]
},
"code": 0,
"msg": "检测成功"
}
请求示例代码:
请替换占位值后在服务端运行。图片使用原始 Base64 字符串,由表单编码器处理特殊字符;不要手动重复 URL 编码。HTTP 成功后仍需检查业务 code。
# Bash / zsh,cURL 7.76+;Windows 可使用 Git Bash 或 WSL。
curl --fail-with-body --max-time 60 --request POST 'https://api.zjzapi.com/idphoto/check' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'key=YOUR_APP_KEY' \
--data-urlencode 'image=BASE64_ENCODED_IMAGE' \
--data-urlencode 'item_id=YOUR_ITEM_ID'
// Java 11+,保存为 Main.java,编译运行:javac -encoding UTF-8 Main.java && java Main
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;
public class Main {
public static void main(String[] args) throws Exception {
Map<String, String> form = new LinkedHashMap<>();
form.put("key", "YOUR_APP_KEY");
form.put("image", "BASE64_ENCODED_IMAGE");
form.put("item_id", "YOUR_ITEM_ID");
String body = form.entrySet().stream()
.map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8)
+ "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
.collect(Collectors.joining("&"));
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10)).build();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.zjzapi.com/idphoto/check"))
.timeout(Duration.ofSeconds(60))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new IllegalStateException("HTTP " + response.statusCode());
}
// HTTP 成功不代表业务成功,还需检查响应 JSON 中的 code。
System.out.println(response.body());
}
}
# Python 3.8+,需先安装 requests:pip install requests
import requests
response = requests.post(
"https://api.zjzapi.com/idphoto/check",
headers={"Content-Type": "application/x-www-form-urlencoded"},
data={
"key": "YOUR_APP_KEY",
"image": "BASE64_ENCODED_IMAGE",
"item_id": "YOUR_ITEM_ID",
},
timeout=(10, 60),
)
response.raise_for_status()
# 按接口文档检查业务 code,再读取 data。
print(response.json())
<?php
// PHP 7.2+,需启用 cURL 扩展。
// 使用 http_build_query 编码表单,不能直接向 CURLOPT_POSTFIELDS 传数组。
$form = [
'key' => 'YOUR_APP_KEY',
'image' => 'BASE64_ENCODED_IMAGE',
'item_id' => 'YOUR_ITEM_ID',
];
$curl = curl_init('https://api.zjzapi.com/idphoto/check');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($form),
CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
]);
$result = curl_exec($curl);
$error = curl_error($curl);
$status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($result === false) {
throw new RuntimeException($error);
}
if ($status_code < 200 || $status_code >= 300) {
throw new RuntimeException('HTTP ' . $status_code);
}
// 按接口文档检查响应 JSON 中的业务 code,再读取 data。
echo $result;
// Go 1.16+,仅使用标准库。
package main
import (
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
)
func main() {
form := url.Values{
"key": {"YOUR_APP_KEY"},
"image": {"BASE64_ENCODED_IMAGE"},
"item_id": {"YOUR_ITEM_ID"},
}
request, err := http.NewRequest("POST", "https://api.zjzapi.com/idphoto/check", strings.NewReader(form.Encode()))
if err != nil {
panic(err)
}
request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
client := &http.Client{Timeout: 60 * time.Second}
response, err := client.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
if response.StatusCode < 200 || response.StatusCode >= 300 {
panic(fmt.Errorf("HTTP %d", response.StatusCode))
}
result, err := io.ReadAll(response.Body)
if err != nil {
panic(err)
}
// 按接口文档检查响应 JSON 中的业务 code,再读取 data。
fmt.Println(string(result))
}
// Node.js 18+,保存为 request.mjs;仅在服务端运行,勿将凭据放进浏览器代码。
const form = new URLSearchParams([
["key", "YOUR_APP_KEY"],
["image", "BASE64_ENCODED_IMAGE"],
["item_id", "YOUR_ITEM_ID"],
]);
const response = await fetch('https://api.zjzapi.com/idphoto/check', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: form,
signal: AbortSignal.timeout(60000),
});
if (!response.ok) {
throw new Error('HTTP ' + response.status);
}
// 按接口文档检查业务 code,再读取 data。
console.log(await response.json());
// C# 10 / .NET 6+,放入控制台项目的 Program.cs。
using System;
using System.Collections.Generic;
using System.Net.Http;
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
using var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("key", "YOUR_APP_KEY"),
new KeyValuePair<string, string>("image", "BASE64_ENCODED_IMAGE"),
new KeyValuePair<string, string>("item_id", "YOUR_ITEM_ID"),
});
// FormUrlEncodedContent 自动设置 application/x-www-form-urlencoded 并编码字段。
using var response = await client.PostAsync("https://api.zjzapi.com/idphoto/check", content);
response.EnsureSuccessStatusCode();
// 按接口文档检查响应 JSON 中的业务 code,再读取 data。
Console.WriteLine(await response.Content.ReadAsStringAsync());