View Categories

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

接口概述 #

本接口提供一站式证件照制作和合规性检测服务。首先对用户上传的图片进行证件照制作（包括人脸检测、背景替换、尺寸调整等），然后对制作完成的证件照进行多项合规性检测。

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

请求格式 #

Headers #

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

请求体参数 #

必须参数

参数类型说明
widthint证件照目标宽度（像素）
heightint证件照目标高度（像素）

图片输入（二选一）

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

制作参数

参数类型默认值说明
spec_idintnull规格ID（可选，用于预设参数）
fair_levelfloat0.0美颜等级
colorarraynull背景颜色配置数组
enhance_image_qualityint1图像质量增强（0/1）
head_regionint0头部区域选择（0:包含头发，1:仅脸颊）
align_faceint0人脸姿态调整（0/1）
file_formatint0输出格式（0:PNG，1:JPG）
dpifloat300.0图片分辨率
file_size_minint0最小文件大小（单位KB，仅JPG生效；0表示不限制）
file_size_maxint0最大文件大小（单位KB，仅JPG生效；0表示不限制）
apply_sharpeningint0达不到最小体积时是否进行轻度锐化以增大文件体积（0/1，仅JPG且设置了file_size_min>0时可能生效）

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

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

人脸比例参数

参数类型默认值说明
face_ratio_minfloat0.55人脸最小比例
face_ratiofloat0.8人脸最大比例
head_height_ratio_minfloat0.01头部高度最小比例
head_height_ratio_maxfloat1.0头部高度最大比例
eye_distance_ratio_minfloat0.01双眼间距最小比例
eye_distance_ratio_maxfloat1.0双眼间距最大比例

位置参数

参数类型默认值说明
head_top_gap_ratiofloat0.08头顶离上边缘距离比例
eyes_to_botttom_ratio_minfloat0.46眼睛离下边缘最小距离比例

基础检测参数

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

外观检测参数

参数类型默认值说明
hat_checkint0帽子检测（0/1）
glasses_checkint0眼镜检测（0/1）
glasses_glareint0眼镜反光检测（0/1）
sunglasses_checkint0墨镜检测（0/1）
necklace_checkint0项链检测（0/1）
earring_checkint0耳环检测（0/1）
facemask_checkint0口罩检测（0/1）

质量检测参数

参数类型默认值说明
contrast_minfloat0.0最低对比度要求。推荐范围：
• 宽松要求：20-40（适用于普通应用）
• 标准要求：40-80（推荐证件照）
• 严格要求：80-150（高质量要求）
• 超严格：>150（专业摄影级别）
设置为0表示不检测对比度
brightness_check_minint0最低亮度值。推荐范围：
• 宽松要求：80-120（光线较暗环境）
• 标准要求：100-130（推荐证件照）
• 严格要求：110-140（高质量要求）
设置为0表示不检测最低亮度
brightness_check_maxint255最高亮度值。推荐范围：
• 宽松要求：200-220（允许轻微过曝）
• 标准要求：170-190（推荐证件照）
• 严格要求：160-180（高质量要求）
设置为255表示不检测最高亮度
face_clarity_checkint0面部清晰度检测（0/1）
image_noise_checkint0图像噪声检测（0/1）
color_cast_checkint0偏色检测（0/1）

姿态检测参数

参数类型默认值说明
body_pose_checkint0身体姿态检测（0/1）
shoulder_checkint0肩膀缺失检测（0/1）
horizontal_shoulder_checkint0肩膀水平检测（0/1）
head_crop_checkint0头部缺失检测（0/1）

背景与阴影检测参数

参数类型默认值说明
bg_shadow_checkint0背景阴影检测（0/1）
neck_shadow_checkint0脖子阴影检测（0/1）
face_balanced_light_checkint0阴阳脸检测（0/1）
bg_colorsarraynull背景颜色合规检测集合（如 [“red”,”white”,”blue”]）；为空表示不检测

其他检测参数

参数类型默认值说明
mouth_open_checkint0张嘴检测（0/1）
brow_checkint0眉毛遮挡检测（0/1）
eye_checkint0眼睛遮挡检测（0/1）
ear_checkint0耳朵遮挡检测（0/1）
nose_checkint0鼻子遮挡检测（0/1）
mouth_checkint0嘴巴遮挡检测（0/1）
cheek_full_checkint0脸颊遮挡检测（0/1）
thick_frame_glasses_checkint0粗框眼镜检测（0/1）
shirtless_checkint0光膀检测（0/1）
bg_clothes_similar_checkint0背景服装相似检测（0/1）

质量检测参数详细说明 #

对比度检测 (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/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文件格式不支持
402API点数不足
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 点/次。
  • /make 接口：调用不消耗点数；下载“无水印原图”扣 30 点/次。
  • /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. 用户体验: 对于检测未通过的项目，可以给用户提供具体的改进建议
在线客服
谢谢您的关注，您的请求我们将24小时内回复。
12:01
您好，有任何疑问请与我们联系！
kris

选择聊天工具：