证件照制作+检测接口 API文档

可立图 ClipImg 证件照制作并检测 API 服务

接口概述 #

本接口是证件照制作与合规性检测的深度融合版本，专为高标准证件照应用场景设计。它在完成证件照智能制作（人脸检测、抠图、裁剪、美颜、换底）的基础上，立即对生成的成品照进行全方位的合规性检测。

核心优势：

• 闭环处理：一次调用即可完成“制作+质检”全流程，无需分别调用制作和检测接口，降低开发复杂度。
• 精准反馈：检测针对的是最终生成的证件照（而非原图），能准确反映成品是否符合官方标准（如背景是否纯净、裁剪比例是否正确）。
• 即时纠错：如果制作出的照片存在闭眼、反光、阴影等问题，接口会返回详细的错误信息，便于前端即时提示用户重拍。

典型使用场景 #

1. 护照/签证办理：各国签证照片对头部比例、背景色、面部遮挡有严格要求，使用本接口可确保输出照片符合相关部门标准。
2. 国家级考试报名：如高考、研考、公考等，系统通常有自动审核机制，本接口可作为预审核工具，提高报名照片通过率。
3. 驾驶证/社保卡采集：此类证件对照片质量（如亮度、清晰度、无阴影）要求极高，通过本接口的质量检测功能可有效筛除不合格照片。
4. 无人值守自助终端：在自助照相亭中，自动判断拍摄质量并引导重拍，实现全自动化服务。
5. 证件照回执办理：针对身份证、居住证等需要出具官方检测回执的业务，利用本接口的严格检测能力，确保照片符合相关部门的入库标准，提升回执办理成功率。

• 接口地址: https://www.clipimg.com/api/idphoto/make_and_check
• Postman: 文档
• 请求方式: POST
• Content-Type: application/json
• 需要API Key: 是

请求格式 #

Headers #

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

请求体参数 #

必须参数

参数	类型	说明
width	int	证件照目标宽度（像素）
height	int	证件照目标高度（像素）

图片输入（二选一）

参数	类型	说明
file	string	Base64 编码的图片数据
file_url	string	可直接访问的图片 URL（支持 JPG/PNG；单文件最大 20MB）。若同时提供 file 与 file_url，以 file 优先

制作参数

参数	类型	默认值	说明
spec_id	int	null	规格ID（可选，用于预设参数，如传入则自动填充宽高及其他规格参数）
fair_level	float	0.0	美颜等级，取值 0.0-1.0，0表示不美颜
color	array	null	背景颜色配置数组，默认包含蓝、红、白三种颜色
enhance_image_quality	int	1	图像质量增强（0/1），1表示开启
head_region	int	0	头部区域选择（0:包含头发耳朵，1:仅脸颊） 0:  1:
align_face	int	0	人脸姿态调整（0/1），1表示开启自动矫正
file_format	int	0	输出格式（0:PNG，1:JPG）
dpi	float	300.0	图片分辨率
file_size_min	int	0	最小文件大小（单位KB，仅JPG生效；0表示不限制）
file_size_max	int	0	最大文件大小（单位KB，仅JPG生效；0表示不限制）
apply_sharpening	int	0	达不到最小体积时是否进行轻度锐化以增大文件体积（0/1，仅JPG且设置了file_size_min>0时可能生效）
watermark_id	int	null	自定义水印id，需要在API管理上传

检测阶段参数（系统派生）

参数	类型	默认值	说明
file_format_check	string	系统推导	检测阶段内部使用的图片格式标记，系统将根据 file_format 自动设置：file_format=0 → png，file_format=1 → jpg；无需传入

人脸比例参数

参数	类型	默认值	说明
face_ratio_min	float	0.55	人脸最小比例
face_ratio	float	0.8	人脸最大比例
head_height_ratio_min	float	0.01	头部高度最小比例
head_height_ratio_max	float	1.0	头部高度最大比例
eye_distance_ratio_min	float	0.01	双眼间距最小比例
eye_distance_ratio_max	float	1.0	双眼间距最大比例

位置参数

参数	类型	默认值	说明
head_top_gap_ratio	float	0.08	头顶离上边缘距离比例
eyes_to_botttom_ratio_min	float	0.46	眼睛离下边缘最小距离比例

基础检测参数

参数	类型	默认值	说明
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）

外观检测参数

参数	类型	默认值	说明
hat_check	int	0	帽子检测（0/1）
glasses_check	int	0	眼镜检测（0/1）
glasses_glare	int	0	眼镜反光检测（0/1）
sunglasses_check	int	0	墨镜检测（0/1）
necklace_check	int	0	项链检测（0/1）
earring_check	int	0	耳环检测（0/1）
facemask_check	int	0	口罩检测（0/1）
thick_frame_glasses_check	int	0	粗框眼镜检测（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）

姿态与遮挡检测参数

参数	类型	默认值	说明
body_pose_check	int	0	身体姿态检测（0/1）
shoulder_check	int	0	肩膀缺失检测（0/1）
horizontal_shoulder_check	int	0	肩膀水平检测（0/1）
head_crop_check	int	0	头部缺失检测（0/1）
mouth_open_check	int	0	张嘴检测（0/1）
brow_check	int	0	眉毛遮挡检测（0/1）
eye_check	int	0	眼睛遮挡检测（0/1）
ear_check	int	0	耳朵遮挡检测（0/1）
nose_check	int	0	鼻子遮挡检测（0/1）
mouth_check	int	0	嘴巴遮挡检测（0/1）
cheek_full_check	int	0	脸颊遮挡检测（0/1）
shirtless_check	int	0	光膀检测（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”]）；为空表示不检测

质量检测参数详细说明 #

对比度检测 (contrast_min)

对比度用于评估图像清晰度和边缘锐利程度。

推荐设置指南：

• 0-20: 非常模糊或低对比度图像（通常不合格）
• 20-40: 轻微模糊，适用于对质量要求不高的场景
• 40-80: 标准清晰度，推荐用于证件照（建议值：40-60）
• 80-150: 高清晰度，适用于高质量要求
• >150: 专业级清晰度

常用场景建议：

{
  "普通证件照": {"contrast_min": 40},
  "护照签证": {"contrast_min": 60},
  "高考报名": {"contrast_min": 50},
  "考研报名": {"contrast_min": 45},
  "简历头像": {"contrast_min": 30}
}

亮度检测 (brightness_check_min / brightness_check_max)

亮度用于评估图像的曝光程度和光照质量。

数值含义：

• 0-50: 严重欠曝（过暗，细节丢失）
• 50-100: 轻度欠曝（偏暗，可能影响识别）
• 100-180: 正常曝光（推荐证件照范围）
• 180-200: 轻度过曝（偏亮，但可接受）
• 200-220: 接近过曝边界（仍可用，证件照常见范围）
• 220-255: 严重过曝（过亮，细节丢失）

实测说明: 根据大量证件照测试数据，一般人脸亮度都在220以内。

推荐设置组合：

{
  "宽松标准": {
    "brightness_check_min": 70,
    "brightness_check_max": 220,
    "说明": "较宽松设置"
  },
  "标准证件照": {
    "brightness_check_min": 90,
    "brightness_check_max": 210,
    "说明": "通用推荐"
  },
  "严格要求": {
    "brightness_check_min": 100,
    "brightness_check_max": 200,
    "说明": "较高质量要求"
  },
  "高质量专业": {
    "brightness_check_min": 110,
    "brightness_check_max": 190,
    "说明": "专业级"
  }
}

不同应用场景建议：

{
  "身份证/护照": {"min": 100, "max": 200},
  "高考/考研": {"min": 90, "max": 210},
  "简历头像": {"min": 70, "max": 220},
  "员工证件": {"min": 80, "max": 220}
}

质量参数配置组合建议：

{
  "宽松标准（高通过率）": {
    "contrast_min": 30,
    "brightness_check_min": 70,
    "brightness_check_max": 220,
    "适用场景": "用户体验优先，如社交媒体、会员卡等"
  },
  "标准证件照（推荐）": {
    "contrast_min": 45,
    "brightness_check_min": 90,
    "brightness_check_max": 210,
    "适用场景": "大部分证件照应用，平衡质量和通过率"
  },
  "严格要求（高质量）": {
    "contrast_min": 60,
    "brightness_check_min": 100,
    "brightness_check_max": 200,
    "适用场景": "政府证件、护照等高标准要求"
  }
}

背景颜色配置格式 #

[
  {
    "name": "white",
    "start_color": "#FFFFFF",
    "enc_color": null
  },
  {
    "name": "red",
    "start_color": "#D9001B",
    "enc_color": null
  },
  {
    "name": "blue",
    "start_color": "#02A7F0",
    "enc_color": null
  }
]

文件体积约束与锐化（仅JPG生效） #

为满足部分场景对电子照文件体积的要求，提供以下参数：file_size_min、file_size_max、apply_sharpening。

• 生效前提：仅当输出格式为 JPG（file_format=1）时生效；PNG 为无损编码，不做体积控制与锐化处理。
• 单位说明：file_size_min 与 file_size_max 的单位均为 KB；设置为 0 表示不限制。

处理逻辑（摘要）：

• 若未设置最小/最大体积（均为0），将按默认质量保存（高质量）。
• 若设置了体积约束：
  • 先以高质量尝试保存，若已在范围内则直接使用；
  • 若在最高质量下仍小于 file_size_min：先以最高质量输出；若 apply_sharpening=1，将进行边缘感知的温和锐化以增加细节，从而提升体积，再次尝试满足最小体积；
  • 其他情况则通过质量优化（在合理范围内二分搜索质量）以兼顾清晰度与体积要求；若优化后仍低于最小值，且 apply_sharpening=1，再尝试锐化提升体积。

建议：

• 常见 295×413 像素证件照可根据业务设置如：file_size_min=30~80KB，file_size_max=100~300KB（仅示例，具体可按平台规范调整）。
• apply_sharpening 默认关闭；开启后仅在低于最小体积时进行温和锐化。过小的 file_size_max 可能导致画质下降（为满足上限会降低质量）。

注意：PNG（file_format=0）不参与体积调节与锐化，按无损方式直接保存。

请求示例 #

{
  "file": "base64_encoded_image_data...",
  "width": 295,
  "height": 413,
  "fair_level": 0.3,
  "color": [
    {
      "name": "white",
      "start_color": "#FFFFFF",
      "enc_color": null
    }
  ],
  "dpi": 300,
  "file_format": 1,
  "enhance_image_quality": 1,
  "align_face": 0,
  "head_region": 0,
  "face_ratio_min": 0.55,
  "face_ratio": 0.8,
  "head_height_ratio_min": 0.01,
  "head_height_ratio_max": 0.85,
  "eye_distance_ratio_min": 0.01,
  "eye_distance_ratio_max": 0.35,
  "head_top_gap_ratio": 0.12,
  "eyes_to_botttom_ratio_min": 0.75,
  "facepose": 20,
  "eye_blink_check": 1,
  "mouth_neutral_check": 1,
  "glasses_glare": 1,
  "file_size_min": 60,
  "file_size_max": 240,
  "apply_sharpening": 1
}

响应格式 #

成功响应 #

{
  "code": 0,
  "msg": "证件照制作和检测都成功",
  "data": {
    "make": {
      "code": 0,
      "result": {
        "image_id": "unique_image_id",
        "filenames": [
          {
            "img_name": "image_name",
            "bg_color": "white",
            "preview_img_name": "preview_name",
            "print_img_name": "print_name",
            "preview_print_img_name": "print_preview_name"
          }
        ],
        "face_attr": {
          "face_ratio": 0.6234,
          "head_height_ratio": 0.7456,
          "eyes_to_botttom_ratio": 0.7234,
          "top_gap_ratio": 0.1123,
          "eye_distance_ratio": 0.2345
        }
      }
    },
    "check": {
      "code": 0,
      "result": {
        "check_result": [
          {
            "key": "eye_blink_check",
            "name": "闭眼检测",
            "check": 1,
            "error_msg": null
          },
          {
            "key": "mouth_neutral_check",
            "name": "表情检测",
            "check": 1,
            "error_msg": null
          }
        ],
        "check_info": [
          {
            "key": "face_ratio",
            "name": "最终人脸比例",
            "value": 0.6234
          },
          {
            "key": "head_height_ratio",
            "name": "最终头部高度比例",
            "value": 0.7456
          },
          {
            "key": "head_pitch",
            "name": "头部俯仰角",
            "value": 2.34
          },
          {
            "key": "head_yaw",
            "name": "头部偏转角",
            "value": 1.23
          },
          {
            "key": "head_roll",
            "name": "头部倾斜角",
            "value": 0.89
          }
        ]
      }
    }
  }
}

部分检测未通过响应 #

{
  "code": 431,
  "msg": "证件照制作成功但检测有部分项未通过",
  "data": {
    "make": {
      "code": 0,
      "result": { /* 制作成功结果 */ }
    },
    "check": {
      "code": 0,
      "result": {
        "check_result": [
          {
            "key": "glasses_glare_check",
            "name": "眼镜反光检测",
            "check": 0,
            "error_msg": "检测到眼镜反光"
          }
        ],
        "check_info": [ /* 检测信息 */ ]
      }
    }
  }
}

各语言调用示例 #

以下示例演示调用 /make_and_check 接口的最小化请求（仅必填 + 常用项），使用域名 https://www.clipimg.com/api；将 YOUR_API_KEY 替换为真实密钥。

curl #

curl -X POST "https://www.clipimg.com/api/idphoto/make_and_check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "BASE64_IMAGE_DATA",
    "width": 295,
    "height": 413,
    "file_format": 1,
    "dpi": 300,
    "file_size_min": 60,
    "file_size_max": 240,
    "apply_sharpening": 1
  }'

使用 file_url 输入（可选）

以下为使用网络图片 URL 输入的最小示例：

• curl

curl -X POST "https://www.clipimg.com/api/idphoto/make_and_check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/path/to/photo.jpg",
    "width": 295,
    "height": 413,
    "file_format": 1,
    "dpi": 300
  }'

• Python（requests）

import json, requests

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

payload = {
    "file_url": "https://example.com/path/to/photo.jpg",
    "width": 295,
    "height": 413,
    "file_format": 1,
    "dpi": 300
}

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

Python（requests） #

import base64, json, requests

api = "https://www.clipimg.com/api/idphoto/make_and_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,
    "width": 295,
    "height": 413,
    "file_format": 1,
    "dpi": 300,
    "file_size_min": 60,
    "file_size_max": 240,
    "apply_sharpening": 1
}

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

Node.js（axios） #

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

(async () => {
  const imgB64 = fs.readFileSync('photo.jpg').toString('base64');
  const resp = await axios.post(
  'https://www.clipimg.com/api/idphoto/make_and_check',
    {
      file: imgB64,
      width: 295,
      height: 413,
      file_format: 1,
      dpi: 300,
      file_size_min: 60,
      file_size_max: 240,
      apply_sharpening: 1
    },
    { headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, timeout: 60000 }
  );
  console.log(resp.data);
})();

PHP（cURL 扩展） #

<?php
$imgB64 = base64_encode(file_get_contents('photo.jpg'));
$data = [
  'file' => $imgB64,
  'width' => 295,
  'height' => 413,
  'file_format' => 1,
  'dpi' => 300,
  'file_size_min' => 60,
  'file_size_max' => 240,
  'apply_sharpening' => 1
];

$ch = curl_init('https://www.clipimg.com/api/idphoto/make_and_check');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    'X-API-Key: YOUR_API_KEY',
    'Content-Type: application/json'
  ],
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($data, JSON_UNESCAPED_UNICODE),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 60
]);
$resp = curl_exec($ch);
if (curl_errno($ch)) { die('cURL Error: '.curl_error($ch)); }
curl_close($ch);
echo $resp;

Java（OkHttp） #

import java.nio.file.*;
import java.util.Base64;
import okhttp3.*;

public class Demo {
  public static void main(String[] args) throws Exception {
  String api = "https://www.clipimg.com/api/idphoto/make_and_check";
    String apiKey = "YOUR_API_KEY";
    byte[] img = Files.readAllBytes(Paths.get("photo.jpg"));
    String imgB64 = Base64.getEncoder().encodeToString(img);
    String json = "{" +
      "\"file\":\"" + imgB64 + "\"," +
      "\"width\":295,\"height\":413,\"file_format\":1,\"dpi\":300," +
      "\"file_size_min\":60,\"file_size_max\":240,\"apply_sharpening\":1" +
    "}";

    OkHttpClient client = new OkHttpClient.Builder().build();
    RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));
    Request req = new Request.Builder()
        .url(api)
        .addHeader("X-API-Key", apiKey)
        .post(body)
        .build();
    try (Response resp = client.newCall(req).execute()) {
      System.out.println(resp.code());
      System.out.println(resp.body().string());
    }
  }
}

C#（HttpClient + System.Text.Json） #

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

class Program {
  static async Task Main() {
  var api = "https://www.clipimg.com/api/idphoto/make_and_check";
    var apiKey = "YOUR_API_KEY";
    var imgB64 = Convert.ToBase64String(await File.ReadAllBytesAsync("photo.jpg"));
    var payload = new {
      file = imgB64,
      width = 295,
      height = 413,
      file_format = 1,
      dpi = 300,
      file_size_min = 60,
      file_size_max = 240,
      apply_sharpening = 1
    };
    using var http = new HttpClient();
    var req = new HttpRequestMessage(HttpMethod.Post, api);
    req.Headers.Add("X-API-Key", apiKey);
    req.Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
    var resp = await http.SendAsync(req);
    Console.WriteLine((int)resp.StatusCode);
    Console.WriteLine(await resp.Content.ReadAsStringAsync());
  }
}

下载无水印图片（示例） #

• 电子照下载：

curl -X POST "https://www.clipimg.com/api/idphoto/download/{img_name}" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output output.jpg

• 排版照下载：

curl -X POST "https://www.clipimg.com/api/idphoto/print_download/{print_img_name}" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output output_print.jpg

状态码说明 #

状态码	说明
0	制作和检测都成功
400	参数错误
401	文件格式不支持
402	API点数不足
407	未检测到人脸
408	包含多人
409	太靠近摄像头
413	人脸未正对摄像头
416	处理超时
417	太靠近摄像头，无法制作该规格
431	制作成功但检测有部分项未通过
432	制作成功但检测失败

制作阶段错误码说明 #

• 400 参数错误：缺少或非法参数（如 file/width/height 未提供或越界）；请按文档校验入参。
• 401 文件格式不支持：图片编码不被支持或文件损坏；请更换为常见格式（JPG/PNG）且文件完整。
• 407 未检测到人脸：无法定位有效人脸；建议使用清晰、无遮挡、光照均匀的正面照。
• 408 包含多人：检测到多人脸；请使用仅含单人的正面照。
• 409 太靠近摄像头：人脸区域过大或离镜头过近，难以裁切；建议后退拍摄或更换更远景照片。
• 417 太靠近摄像头，无法制作该规格：在人脸比例上限下仍无法满足目标规格；可降低人脸比例参数或更换原图。
• 416 处理超时：处理耗时超出限制（文件过大/网络或服务负载波动）；可重试或压缩后再试。

提示：402 API点数不足通常发生在下载无水印图片时，非制作错误；431/432 为制作成功后的检测结果，不属于制作错误。

图片访问URL #

（以下为路径，实际访问请加前缀 https://www.clipimg.com/api）

预览图片 #

• 电子照预览: /idphoto/preview/{preview_img_name}
• 排版照预览: /idphoto/print_preview/{preview_print_img_name}

下载图片 #

• 电子照下载: /idphoto/download/{img_name}（需要POST与APIKEY验证；下载无水印图片会消耗点数）
• 排版照下载: /idphoto/print_download/{print_img_name}（需要POST与APIKEY验证；下载无水印图片会消耗点数）

扣点规则说明 #

API点数消耗规则（最新） #

• /make_and_check 接口：调用不消耗点数；下载“无水印原图”扣 50 点/次；下载“无水印排版照”扣 50 点/次。
• /make 接口：调用不消耗点数；下载“无水印原图”扣 30 点/次；下载“无水印排版照”扣 50 点/次。
• /check 接口：调用即扣 1 点/次（独立检测收费）。

优势说明 #

使用 /make_and_check 接口相比先 /make 再独立调用 /check 更加经济：

• /make_and_check 本身不扣点（仅下载无水印时扣点）；
• 独立 /check 接口调用会扣检测点数；
• 同时 /make_and_check 检测针对制作后的成品图，结果更贴近最终输出。

典型场景参数 #

1. 基础证件照制作+基本检测 #

仅开启必要的检测项，适合一般用户：

{
  "eye_blink_check": 1,
  "mouth_neutral_check": 1,
  "facepose": 20
}

2. 严格合规检测 #

开启所有相关检测项，适合正式证件：

{
  "eye_blink_check": 1,
  "mouth_neutral_check": 1,
  "glasses_glare": 1,
  "face_clarity_check": 1,
  "bg_shadow_check": 1,
  "neck_shadow_check": 1
}

3. 自定义规格证件照 #

使用spec_id预设参数，减少参数配置：

{
  "spec_id": 1,
  "fair_level": 0.3
}

开发建议 #

1. 错误处理: 建议对各种状态码进行完整的错误处理
2. 参数校验: 在发送请求前对参数进行本地校验
3. 图片优化: 建议在上传前对图片进行适当压缩
4. 缓存策略: 可以缓存制作成功的图片，避免重复制作
5. 用户体验: 对于检测未通过的项目，可以给用户提供具体的改进建议

相关推荐 #

• 证件照制作接口文档：基础证件照制作。
• 证件照合规性检测接口文档：独立合规性检测。