可立图ClipImg证件照API技术文档：一站式智能证件照制作与合规检测

概述

可立图ClipImg证件照API是一套功能强大的智能图像处理服务，提供证件照制作、合规性检测、回执办理等核心能力。通过简单的API调用，开发者可以快速为应用集成专业的证件照处理功能，适用于在线报名、政务办理、企业采集等多种场景。

核心接口介绍

1. 证件照制作并检测API（推荐）

接口地址： https://www.clipimg.com/api/idphoto/make_and_check

功能特点：

一站式服务：一次调用完成“制作+检测”全流程
精准反馈：检测针对最终生成的证件照成品
即时纠错：返回详细错误信息，便于前端提示用户

请求示例（Python）：

import base64
import requests

api_key = "YOUR_API_KEY"
api_url = " https://www.clipimg.com/api/idphoto/make_and_check "

# 读取图片并编码为base64
with open("photo.jpg", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode("ascii")

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

payload = {
    "file": img_b64,
    "width": 295,
    "height": 413,
    "spec_id": 1,  # 使用预设规格
    "fair_level": 0.3,  # 美颜等级
    "color": [{"name": "white", "start_color": "#FFFFFF"}],
    "dpi": 300,
    "file_format": 1,  # JPG格式
    "facepose": 20,  # 人脸角度容差
    "eye_blink_check": 1,  # 闭眼检测
    "mouth_neutral_check": 1,  # 表情检测
    "file_size_min": 60,  # 最小文件大小(KB)
    "file_size_max": 240  # 最大文件大小(KB)
}

response = requests.post(api_url, headers=headers, json=payload, timeout=60)
print(response.json())

2. 证件照合规性检测API

接口地址： https://www.clipimg.com/api/idphoto/check

检测维度：

基础合规性：人脸角度、闭眼、表情等
人脸位置与比例：头部比例、眼睛位置等
外观与遮挡：眼镜、帽子、饰品等
图像质量：清晰度、亮度、对比度等
文件属性：格式、大小、分辨率等

请求示例（Node.js）：

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,
    eye_blink_check: 1,
    mouth_neutral_check: 1,
    glasses_check: 1,
    brightness_check_min: 90,
    brightness_check_max: 210,
    contrast_min: 40
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log('检测结果：', response.data);
})
.catch(error => {
    console.error('检测失败：', error.response?.data || error.message);
});

3. 证件照回执办理API

接口地址： https://www.clipimg.com/app/receipt_api.php/submit

功能特点：

全流程自动化：从提交到获取回执全自动处理
多类型支持：身份证、居住证、驾驶证等多种证件
状态追踪：实时查询办理进度

请求示例（PHP）：

 $apiKey,
    'receipt_type_id' => 1,  // 回执类型ID
    'id_photo_url' => ' http://example.com/photo.jpg',
    'custom_fields' => [
        'customer_name' => '张三',
        'customer_phone' => '13812345678',
        'customer_id_card' => '110101199001011234',
        'address' => '北京市朝阳区'
    ],
    'callback_url' => ' http://your-domain.com/callback'
];

$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    die('请求失败：' . curl_error($ch));
}
curl_close($ch);

echo $response;
?>

最佳实践建议

1. 参数配置建议

证件照质量参数推荐：

{
  "标准证件照": {
    "contrast_min": 45,
    "brightness_check_min": 90,
    "brightness_check_max": 210,
    "facepose": 20,
    "eye_blink_check": 1,
    "mouth_neutral_check": 1
  },
  "高要求证件照（护照/签证）": {
    "contrast_min": 60,
    "brightness_check_min": 100,
    "brightness_check_max": 200,
    "facepose": 15,
    "eye_blink_check": 1,
    "mouth_neutral_check": 1,
    "glasses_check": 1
  }
}

2. 错误处理策略

def handle_api_response(response):
    """统一处理API响应"""
    data = response.json()
    
    if response.status_code == 200:
        code = data.get('code', 0)
        
        if code == 0:
            # 成功
            return {'success': True, 'data': data.get('data')}
        elif code == 407:
            # 未识别到人脸
            return {'success': False, 'error': '未识别到人脸，请确保面部清晰可见'}
        elif code == 402:
            # API点数不足
            return {'success': False, 'error': 'API点数不足，请及时充值'}
        elif code == 431:
            # 检测部分未通过
            failed_items = []
            check_result = data.get('data', {}).get('check', {}).get('result', [])
            for item in check_result:
                if item.get('check') == 0:
                    failed_items.append(item.get('name'))
            return {
                'success': False,
                'error': '部分检测未通过',
                'details': failed_items,
                'data': data.get('data')
            }
        else:
            # 其他错误
            return {'success': False, 'error': data.get('msg', '未知错误')}
    else:
        # HTTP错误
        return {'success': False, 'error': f'HTTP错误: {response.status_code}'}

3. 前端集成示例（JavaScript）

class ClipImgClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = ' https://www.clipimg.com/api/idphoto';
    }

    async makeAndCheckPhoto(file, options = {}) {
        const formData = new FormData();
        formData.append('file', file);
        
        // 设置默认参数
        const params = {
            width: 295,
            height: 413,
            spec_id: 1,
            file_format: 1,
            dpi: 300,
            ...options
        };

        // 添加其他参数
        Object.keys(params).forEach(key => {
            if (params[key] !== undefined) {
                formData.append(key, params[key]);
            }
        });

        try {
            const response = await fetch(`${this.baseUrl}/make_and_check`, {
                method: 'POST',
                headers: {
                    'X-API-Key': this.apiKey
                },
                body: formData
            });

            if (!response.ok) {
                throw new Error(`HTTP错误: ${response.status}`);
            }

            return await response.json();
        } catch (error) {
            console.error('API调用失败:', error);
            throw error;
        }
    }

    async checkPhotoCompliance(file, specId = 1) {
        const reader = new FileReader();
        
        return new Promise((resolve, reject) => {
            reader.onload = async (event) => {
                const base64Data = event.target.result.split(',')[1];
                
                const payload = {
                    file: base64Data,
                    spec_id: specId,
                    facepose: 20,
                    eye_blink_check: 1,
                    mouth_neutral_check: 1
                };

                try {
                    const response = await fetch(`${this.baseUrl}/check`, {
                        method: 'POST',
                        headers: {
                            'X-API-Key': this.apiKey,
                            'Content-Type': 'application/json'
                        },
                        body: JSON.stringify(payload)
                    });

                    if (!response.ok) {
                        throw new Error(`HTTP错误: ${response.status}`);
                    }

                    const result = await response.json();
                    resolve(result);
                } catch (error) {
                    reject(error);
                }
            };

            reader.readAsDataURL(file);
        });
    }
}

// 使用示例
const client = new ClipImgClient('YOUR_API_KEY');

// 上传文件处理
document.getElementById('photoInput').addEventListener('change', async (event) => {
    const file = event.target.files[0];
    if (!file) return;

    try {
        // 先进行合规检测
        const checkResult = await client.checkPhotoCompliance(file);
        
        if (checkResult.code === 0 && checkResult.data.check_status) {
            // 检测通过，进行制作
            const makeResult = await client.makeAndCheckPhoto(file, {
                color: [{name: "white", start_color: "#FFFFFF"}],
                fair_level: 0.3
            });
            
            if (makeResult.code === 0) {
                // 制作成功，获取图片URL
                const imageUrl = makeResult.data.make.result.filenames[0].download_url;
                console.log('证件照制作成功:', imageUrl);
            }
        } else {
            // 检测未通过，提示用户
            const failedItems = checkResult.data.check_result
                .filter(item => item.check === 0)
                .map(item => item.name);
            
            alert(`照片不符合要求：\n${failedItems.join('\n')}`);
        }
    } catch (error) {
        console.error('处理失败:', error);
        alert('处理失败，请重试');
    }
});

注意事项

API密钥安全：不要在客户端代码中硬编码API密钥，建议通过后端服务中转调用
图片预处理：建议在上传前对图片进行适当压缩，控制在20MB以内
超时设置：图像处理需要时间，建议设置30秒以上的超时时间
错误重试：对于网络错误或超时，建议实施指数退避重试策略
用户引导：对于检测未通过的情况，提供具体的改进建议给用户

总结

可立图ClipImg证件照API提供了完整的证件照处理解决方案，从基础的制作、检测到专业的回执办理，覆盖了各种使用场景。通过合理的参数配置和错误处理，可以快速为应用集成高质量的证件照处理功能，提升用户体验和业务效率。

技术栈支持： 提供Python、JavaScript、PHP、Java、C#等多种语言的调用示例，方便不同技术背景的开发者集成使用。

文档资源：

在线演示： https://apidemo.clipimg.com
Postman文档： https://www.clipimg.com/api/docs
技术支持：contact@clipimg.com

本文档基于可立图ClipImg官方API文档整理，具体实现细节请以官方最新文档为准。

概述