证件照制作API接入指南：700+规格一键生成

概述

本指南旨在为开发者提供可立图ClipImg证件照制作API的纯粹技术接入参考。该API的核心能力是将用户上传的生活照或自拍照，自动处理为符合特定规格的标准证件照。它集成了人脸检测、人像抠图、智能裁剪、背景替换、美颜美肤等模块，并支持输出高清电子照及排版照。

通过参数配置，开发者可以通过一个接口应对数百种证件照规格需求。

典型的技术应用场景

1. 移动端应用：为小程序或APP提供后端图像处理支持。
2. 企业/校园信息化系统：集成至OA、教务系统，用于统一采集员工或学生照片。
3. 政务/考试报名平台：在报名流程中嵌入，确保上传照片符合官方尺寸和背景要求。
4. 自助照相设备：为线下终端提供核心的图像处理引擎。

1. 接口基础信息

• 接口地址 : https://www.clipimg.com/api/idphoto/make
• 请求方式 : POST
• Content-Type : application/json
• 认证方式 : X-API-Key (在请求头中携带)

2. 请求参数详解

2.1 Headers

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

2.2 请求体参数

2.2.1 必须参数

参数	类型	说明
width	int	证件照目标宽度（像素），若提供 spec_id 可省略
height	int	证件照目标高度（像素），若提供 spec_id 可省略

2.2.2 图片输入（二选一）

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

2.2.3 制作参数

参数	类型	默认值	说明
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:仅脸颊）
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有效）
watermark_id	int	null	自定义水印id

背景颜色配置格式

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

3. 多语言调用示例

以下示例演示调用 /make 接口的请求，使用域名 https://www.clipimg.com/api；请将 YOUR_API_KEY 替换为真实的密钥。

3.1 curl

curl -X POST "https://www.clipimg.com/api/idphoto/make" \
  -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
  }'

3.2 Python (requests)

import base64, json, requests

api = "https://www.clipimg.com/api/idphoto/make"
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,
    "fair_level": 0.3
}

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

3.3 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',
    {
      file: imgB64,
      width: 295,
      height: 413,
      file_format: 1,
      dpi: 300,
      fair_level: 0.3
    },
    { headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, timeout: 60000 }
  );
  console.log(resp.data);
})();

3.4 PHP (cURL 扩展)

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

$ch = curl_init('https://www.clipimg.com/api/idphoto/make');
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;
?>

3.5 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";
    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," +
      "\"fair_level\":0.3" +
    "}";

    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());
    }
  }
}

3.6 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";
    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,
      fair_level = 0.3
    };
    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());
  }
}

4. 响应格式与状态码

4.1 成功响应

{
  "code": 0,
  "msg": "Success",
  "data": {
    "image_id": "unique_image_id",
    "filenames": [
      {
        "preview_url": "https://...",
        "download_url": "https://...",
        "img_name": "d00a4..._white",
        "color_name": "white",
        "bg_color": "#FFFFFF",
        "print_img_name": "d00a4..._print_white",
        "print_url": "https://..."
      }
    ],
    "face_attr": {
      "face_ratio": 0.6234,
      "head_height_ratio": 0.7456
    }
  }
}

4.2 错误响应

{
  "code": 407,
  "msg": "未识别到人脸，请确保面部清晰可见，光线充足，并正对摄像头",
  "data": []
}

4.3 状态码说明

状态码	说明
0	成功
400	参数错误
401	暂不支持你上传的照片格式
402	API点数不足
407	未识别到人脸
408	检测到多人
413	人脸未正对摄像头
416	处理超时
417	图片中人脸过大

5. 开发建议与注意事项

• 体积与锐化 ：JPG格式下可通过 file_size_min、file_size_max 和 apply_sharpening 控制文件体积。PNG为无损格式，不参与此逻辑。
• 错误处理 ：建议对400、407等常见状态码进行完整的错误处理，并根据msg字段给出用户友好的提示。
• 参数校验：在发送请求前，建议对参数进行本地校验（如校验宽高是否为有效数值）。
• 指纹/照片下载 ：调用 /idphoto/download/{img_name} 接口下载无水印原图时，需使用POST方法并携带X-API-Key。
• 结果保留：制作结果保留1小时，请及时下载。