证件照合规性检测API接口 - 40+项官方标准检测

可立图 ClipImg 证件照合规性检测 API 服务

接口概述 #

本接口提供全方位的证件照合规性检测服务，旨在帮助开发者快速判断用户上传的照片是否符合特定的证件照标准。接口支持对照片进行多维度的深度分析，包括但不限于：

基础合规性：检测人脸角度（抬头、低头、侧脸）、闭眼、视线方向、表情自然度等。
人脸位置与比例：精确计算人脸在照片中的占比、头部位置、眼睛位置等，确保符合构图规范。
外观与遮挡：识别是否佩戴眼镜、墨镜、帽子、口罩、项链、耳环等饰品，以及眉毛、眼睛、耳朵等关键部位是否被遮挡。
图像质量：分析照片的清晰度、亮度、对比度、噪点、偏色情况，以及背景是否纯净、是否有阴影等。
文件属性：检查文件格式、大小、分辨率（DPI）等物理属性。

通过返回详细的检测结果和具体的数值信息（如角度值、占比值），开发者可以灵活地构建前端提示或后端审核逻辑。

典型使用场景 #

自助证件照拍摄/制作应用：在用户拍摄或上传照片后立即进行预检测，实时引导用户调整姿势或环境（如提示“光线太暗”、“请正对镜头”），提高成片率。
在线报名/办证系统：用于考试报名、证件办理等流程，自动审核用户提交的照片是否符合官方标准，替代人工初审，提升效率。
企业/校园档案管理：规范采集员工或学生的标准证件照，确保档案照片的统一性和专业性。
照片打印服务：在打印前进行质量把关，避免因分辨率不足或模糊导致的废片。

接口地址: https://www.clipimg.com/api/idphoto/check
在线演示: 试一试
Postman: 文档
请求方式: POST
Content-Type: application/json
需要API Key: 是
计费说明: 调用即扣 1 点/次

请求格式 #

Headers #

X-API-Key: your_api_key_here
Content-Type: application/json

请求体参数 #

必须参数

参数	类型	说明
file	string	Base64 编码的图片数据

规格参数（可选）

参数	类型	说明
spec_id	int	规格ID（可选，用于预设参数，如传入则自动填充宽高及其他检测阈值）
width	int	证件照目标宽度（像素），若提供 `spec_id` 可省略
height	int	证件照目标高度（像素），若提供 `spec_id` 可省略
dpi	float	图片分辨率，默认300.0。需满足 value > 0 才会启用检测

基础检测参数

参数	类型	默认值	说明
facepose	int	20	人脸角度容差（度数）。建议设置：15-30°（允许轻微偏转）、5-15°（严格要求），超出设定角度的照片将被标记为不合规，设置为0表示不检测角度
eye_blink_check	int	1	闭眼检测（0/1）
mouth_neutral_check	int	1	表情检测（0/1）
gaze_check	int	0	视线检测（0/1）

人脸比例与位置参数

参数	类型	默认值	说明
head_region	int	0	头部区域选择（0:包含头发耳朵，1:仅脸颊）
face_ratio_min	float	0.55	人脸最小比例。需满足 0 < min < max < 1 才会启用检测
face_ratio	float	0.8	人脸最大比例。需满足 0 < min < max < 1 才会启用检测
head_height_ratio_min	float	0.01	头部高度最小比例。需满足 0 < min < max < 1 才会启用检测
head_height_ratio_max	float	1.0	头部高度最大比例。需满足 0 < min < max < 1 才会启用检测
eye_distance_ratio_min	float	0.01	双眼间距最小比例。需满足 0 < min < max < 1 才会启用检测
eye_distance_ratio_max	float	1.0	双眼间距最大比例。需满足 0 < min < max < 1 才会启用检测
head_top_gap_ratio	float	0.08	头顶离上边缘距离比例。需满足 0 < value < 1 才会启用检测
eyes_to_botttom_ratio_min	float	0.46	眼睛离下边缘最小距离比例。需满足 0 < value < 1 才会启用检测

外观检测参数

参数	类型	说明
hat_check	int	帽子检测（0/1）
glasses_check	int	眼镜检测（0/1）
glasses_glare	int	眼镜反光检测（0/1）
sunglasses_check	int	墨镜检测（0/1）
necklace_check	int	项链检测（0/1）
earring_check	int	耳环检测（0/1）
facemask_check	int	口罩检测（0/1）
thick_frame_glasses_check	int	粗框眼镜检测（0/1）

质量检测参数

参数	类型	默认值	说明
contrast_min	float	0.0	最低对比度要求。推荐范围：20-40（宽松），40-80（标准），80-150（严格）。需满足 value > 0 才会启用检测
brightness_check_min	int	0	最低亮度值。推荐范围：80-120（宽松），100-130（标准），110-140（严格）。需满足 0 <= min < max <= 255 才会启用检测
brightness_check_max	int	255	最高亮度值。推荐范围：200-220（宽松），170-190（标准），160-180（严格）。需满足 0 <= min < max <= 255 才会启用检测
face_clarity_check	int	0	面部清晰度检测（0/1）
image_noise_check	int	0	图像噪声检测（0/1）
color_cast_check	int	0	偏色检测（0/1）
file_size_min	int	0	最小文件大小（单位KB）。需满足 0 < min < max 才会启用检测
file_size_max	int	0	最大文件大小（单位KB）。需满足 0 < min < max 才会启用检测
file_format	string	null	检测照片格式（如 ‘jpg’, ‘png’）。仅支持 ‘jpg’, ‘jpeg’, ‘png’ 才会启用检测

姿态与遮挡检测参数

参数	类型	说明
body_pose_check	int	身体姿态检测（0/1）
shoulder_check	int	肩膀缺失检测（0/1）
horizontal_shoulder_check	int	肩膀水平检测（0/1）
head_crop_check	int	头部缺失检测（0/1）
mouth_open_check	int	张嘴检测（0/1）
brow_check	int	眉毛遮挡检测（0/1）
eye_check	int	眼睛遮挡检测（0/1）
ear_check	int	耳朵遮挡检测（0/1）
nose_check	int	鼻子遮挡检测（0/1）
mouth_check	int	嘴巴遮挡检测（0/1）
cheek_full_check	int	脸颊遮挡检测（0/1）
shirtless_check	int	光膀检测（0/1）

背景与阴影检测参数

参数	类型	默认值	说明
bg_shadow_check	int	0	背景阴影检测（0/1）
neck_shadow_check	int	0	脖子阴影检测（0/1）
face_balanced_light_check	int	0	阴阳脸检测（0/1）
solid_bg_check	int	0	纯色背景检测（0/1）
bg_clothes_similar_check	int	0	背景服装相似检测（0/1）
bg_colors	list	null	背景颜色合规检测集合（如 [“red”,”white”,”blue”]）；为空表示不检测

请求示例 #

{
  "file": "base64_encoded_image_data...",
  "spec_id": 1,
  "facepose": 20,
  "eye_blink_check": 1,
  "mouth_neutral_check": 1,
  "glasses_glare": 1,
  "bg_colors": ["white", "blue"]
}

响应格式 #

成功响应 #

{
  "code": 0,
  "msg": "Success",
  "data": {
    "check_status":false,
    "check_result": [
      {
        "key": "pic_height_check",
        "check": 0,
        "name": "照片高度检测"
      },
      {
        "key": "pic_width_check",
        "check": 0,
        "name": "照片宽度检测"
      },
      {
        "key": "eye_center_check",
        "check": 1,
        "name": "双眼中心在画面正中心检测"
      }
    ],
    "check_info": [
      {
        "key": "head_pitch",
        "value": 14.82,
        "name": "头部上下抬头偏移角度"
      },
      {
        "key": "head_yaw",
        "value": 0.26,
        "name": "头部前后旋转偏移角度"
      },
      {
        "key": "pic_w",
        "value": 914,
        "name": "照片宽度"
      },
      {
        "key": "pic_h",
        "value": 1280,
        "name": "照片高度"
      }
    ]
  }
}

响应参数说明 #

基础字段

参数	类型	说明
check_status	boolean	检测总状态。全部检测项通过时为 true，否则为 false

check_result (检测结果)

Key	说明
pic_height_check	照片高度检测
pic_width_check	照片宽度检测
file_size_check	文件大小检测
file_type_check	照片格式检测
dpi_check	照片分辨率检测
eye_center_check	双眼中心在画面正中心检测
eyes_to_botttom_check	眼睛距底部距离检测
eye_distance_check	双眼间距检测
top_gap_check	发际线距顶部检测
head_height_check	头部高度检测
face_ratio_check	脸部宽度检测
head_pitch_check	头部上下抬头检测
head_yaw_check	头部前后转头检测
head_roll_check	头部左右偏头转检测
gaze_check	视线检测
eye_blink	闭眼检测
mouth_neutral	嘴部表情自然
mouth_open_check	张嘴检测
hat_check	不允许戴帽子
glasses_check	不允戴眼镜
sunglasses_check	墨镜检测
glasses_glare_check	眼镜镜片反光检测
thick_frame_glasses	粗框眼镜检测
necklace_check	不允戴项链
earring_check	不允戴耳环
facemask_check	口罩检测
brow_check	眉毛遮挡
eye_check	眼睛遮挡
ear_check	耳朵遮挡
nose_check	鼻子遮挡
mouth_check	嘴巴遮挡
cheek_full_check	脸颊遮挡检测
shoulder_check	肩膀缺失检测
horizontal_shoulder_check	肩膀水平检测
body_pose_check	身体姿态检测
head_crop_check	头部缺失检测
shirtless_check	光膀检测
solid_bg_check	纯色背景检测
bg_color_check	背景色检测
bg_shadow_check	背景阴影检测
neck_shadow_check	脖子阴影检测
bg_clothes_similar_check	衣服和背景相似检测
contrast_check	对比度检测
brightness_check_min	面部亮度过低
brightness_check_max	面部亮度过亮
face_balanced_light	阴阳脸检测
face_clarity	脸部模糊检测
color_cast	偏色检测
image_noise	图像噪声检测

check_info (检测详情)

Key	说明
pic_w	照片宽度
pic_h	照片高度
file_size	文件大小（kb）
file_type	照片格式
dpi	照片DPI
head_pitch	头部上下抬头偏移角度
head_yaw	头部前后旋转偏移角度
head_roll	头部左右偏头偏移角度
eye_center	双眼中心在画面比例
eyes_to_botttom_ratio	眼睛距底部距离比例
eye_distance_ratio	双眼间距比例
top_gap_ratio	发际线距顶部比例
head_height_ratio	头部高度比例
face_ratio	脸部宽度比例
mouth_open_ratio	张嘴比例
contrast	对比度
brightness	亮度
bg_color	背景色

状态码说明 #

状态码	说明
0	成功
400	参数错误
401	暂不支持你上传的照片格式
402	您的API点数已用完，请及时充值
407	未识别到人脸
416	处理超时，请稍后再试
433	人脸关键点检测失败，请更换照片重试

错误码详细说明 #

400 参数错误：file参数错误 或具体参数错误信息。
401 暂不支持你上传的照片格式：暂不支持你上传的照片格式。
402 您的API点数已用完，请及时充值：您的API点数已用完，请及时充值。
407 未识别到人脸：未识别到人脸。
416 处理超时，请稍后再试：处理超时，请稍后再试。
433 人脸关键点检测失败，请更换照片重试：人脸关键点检测失败，请更换照片重试。

扣点规则说明 #

API点数消耗规则 #

/idphoto/check 接口：调用即扣 1 点/次。

各语言调用示例 #

以下示例演示调用 /check 接口的最小化请求。

curl #

curl -X POST "https://www.clipimg.com/api/idphoto/check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "BASE64_IMAGE_DATA",
    "spec_id": 1
  }'

Python（requests） #

import base64, json, requests

api = "https://www.clipimg.com/api/idphoto/check"
headers = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

with open("photo.jpg", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode("ascii")

payload = {
    "file": img_b64,
    "spec_id": 1,
    "facepose": 20
}

r = requests.post(api, headers=headers, data=json.dumps(payload), timeout=60)
print(r.status_code)
print(r.json())

Node.js (axios) #

const axios = require('axios');
const fs = require('fs');

const apiKey = 'YOUR_API_KEY';
const imagePath = 'photo.jpg';
const imageBase64 = fs.readFileSync(imagePath, { encoding: 'base64' });

axios.post('https://www.clipimg.com/api/idphoto/check', {
    file: imageBase64,
    spec_id: 1,
    facepose: 20
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch(error => {
    console.error(error.response ? error.response.data : error.message);
});

PHP (cURL) #

<?php
$apiKey = 'YOUR_API_KEY';
$imagePath = 'photo.jpg';
$imageBase64 = base64_encode(file_get_contents($imagePath));

$data = [
    'file' => $imageBase64,
    'spec_id' => 1,
    'facepose' => 20
];

$ch = curl_init('https://www.clipimg.com/api/idphoto/check');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP Code: $httpCode\n";
echo $response;
?>

Java (OkHttp) #

import okhttp3.*;
import java.io.File;
import java.nio.file.Files;
import java.util.Base64;

public class IdPhotoCheckDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        File file = new File("photo.jpg");
        byte[] fileContent = Files.readAllBytes(file.toPath());
        String imageBase64 = Base64.getEncoder().encodeToString(fileContent);

        String json = "{"
                + "\"file\": \"" + imageBase64 + "\","
                + "\"spec_id\": 1,"
                + "\"facepose\": 20"
                + "}";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);
        Request request = new Request.Builder()
                .url("https://www.clipimg.com/api/idphoto/check")
                .addHeader("X-API-Key", apiKey)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

C# (HttpClient) #

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var apiKey = "YOUR_API_KEY";
        var imagePath = "photo.jpg";
        var imageBase64 = Convert.ToBase64String(File.ReadAllBytes(imagePath));

        var json = $@"{{
            ""file"": ""{imageBase64}"",
            ""spec_id"": 1,
            ""facepose"": 20
        }}";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            
            var response = await client.PostAsync("https://www.clipimg.com/api/idphoto/check", content);
            var result = await response.Content.ReadAsStringAsync();
            
            Console.WriteLine(result);
        }
    }
}

可立图API文档

证件照合规性检测API文档

接口概述 #

典型使用场景 #

请求格式 #

Headers #

请求体参数 #

必须参数

规格参数（可选）

基础检测参数

人脸比例与位置参数

外观检测参数

质量检测参数

姿态与遮挡检测参数

背景与阴影检测参数

请求示例 #

响应格式 #

成功响应 #

响应参数说明 #

基础字段

check_result (检测结果)

check_info (检测详情)

状态码说明 #

错误码详细说明 #

扣点规则说明 #

API点数消耗规则 #

各语言调用示例 #

curl #

Python（requests） #

Node.js (axios) #

PHP (cURL) #

Java (OkHttp) #

C# (HttpClient) #

相关推荐 #