证件照制作API接口文档 - 智能裁剪/美颜/排版

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

接口概述 #

本接口提供一站式的证件照智能制作服务，能够将用户上传的生活照或自拍照自动处理为符合特定规格的标准证件照。接口集成了人脸检测、人像抠图、智能裁剪、背景替换、美颜美肤、服装替换（需配合参数）等核心能力，支持输出高清电子照及排版照。

通过简单的参数配置，开发者可以轻松应对数百种证件照规格需求，无需深入了解图像处理算法。

典型使用场景 #

移动端证件照小程序/APP：为C端用户提供便捷的手机拍证件照服务，支持一键制作、换底色、换装。
企业/校园信息化系统：集成在OA、教务系统中，用于采集员工工牌照、学生学籍照，实现照片风格统一化。
政务/考试报名平台：在报名流程中嵌入证件照制作功能，确保上传的照片符合官方尺寸和背景要求，减少审核成本。
自助照相设备：为线下自助终端提供核心图像处理引擎，实现即拍即得。

接口地址: https://www.clipimg.com/api/idphoto/make
在线演示: 试一试
Postman: 文档
请求方式: POST
Content-Type: application/json
需要API Key: 是

请求格式 #

Headers #

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

请求体参数 #

必须参数

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

图片输入（二选一）

参数	类型	说明
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管理上传

人脸比例参数

参数	类型	默认值	说明
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表示不检测角度

如需更复杂的筛选检测，请使用证件照制作加检测接口

背景颜色配置格式 #

[
  {
    "name": "white",
    "start_color": "#FFFFFF",
    "enc_color": null
  },
  {
    "name": "red",
    "start_color": "#D9001B",
    "enc_color": null
  },
  {
    "name": "blue",
    "start_color": "#02A7F0",
    "enc_color": null
  },
  {
    "name": "SkyBlueGradient",
    "start_color": "#87CEEB",
    "enc_color": "#1E90FF"
  }
]

name: 背景色名称（纯字母）
start_color: 背景色值（Hex）
enc_color: 渐变色结束色值（可选，不传为纯色）

文件体积约束与锐化（仅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,
  "file_size_min": 60,
  "file_size_max": 240,
  "apply_sharpening": 1
}

响应格式 #

成功响应 #

{
  "code": 0,
  "msg": "Success",
  "data": {
    "image_id": "unique_image_id",
    "filenames": [
      {
        "preview_url": "https://...",
        "preview_img_name": "d00a4..._white_preview",
        "download_url": "https://...",
        "img_name": "d00a4..._white",
        "color_name": "white",
        "bg_color": "#FFFFFF",
        "print_img_name": "d00a4..._print_white",
        "preview_print_img_name": "d00a4..._print_white",
        "print_url": "https://...",
        "preview_print_url": "https://..."
      }
    ],
    "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
    }
  }
}

错误响应 #

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

各语言调用示例 #

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

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
  }'

使用 file_url 输入（可选）

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

• 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_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"
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"
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())

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

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;

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

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

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

电子照下载：

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

Python（requests）：

import requests

headers = {"X-API-Key": "YOUR_API_KEY"}

# 电子照下载
url = "https://www.clipimg.com/api/idphoto/download/{img_name}"
# 注意：下载接口需要使用 POST 方法
with requests.post(url, headers=headers, stream=True) as r:
    if r.status_code == 200:
        with open("output.jpg", "wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)
        print("电子照下载成功")
    else:
        print(f"下载失败: {r.status_code} - {r.text}")

# 排版照下载
print_url = "https://www.clipimg.com/api/idphoto/print_download/{print_img_name}"
with requests.post(print_url, headers=headers, stream=True) as r:
    if r.status_code == 200:
        with open("output_print.jpg", "wb") as f:
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)
        print("排版照下载成功")
    else:
        print(f"下载失败: {r.status_code} - {r.text}")

PHP（cURL）：

<?php
$apiKey = 'YOUR_API_KEY';
$imgName = '{img_name}'; // 替换为实际的 img_name
$url = "https://www.clipimg.com/api/idphoto/download/$imgName";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_RETURNTRANSFER => true,
]);

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

if ($httpCode == 200) {
    file_put_contents('output.jpg', $data);
    echo "下载成功";
} else {
    echo "下载失败: $httpCode";
}
?>

Java（OkHttp）：

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

public class DownloadDemo {
  public static void main(String[] args) throws Exception {
    String url = "https://www.clipimg.com/api/idphoto/download/{img_name}";
    String apiKey = "YOUR_API_KEY";

    OkHttpClient client = new OkHttpClient();
    // 下载接口需要 POST 请求，body 可为空
    RequestBody body = RequestBody.create(new byte[0], null);
    Request req = new Request.Builder()
        .url(url)
        .addHeader("X-API-Key", apiKey)
        .post(body)
        .build();

    try (Response resp = client.newCall(req).execute()) {
      if (resp.isSuccessful()) {
        Files.write(Paths.get("output.jpg"), resp.body().bytes());
        System.out.println("下载成功");
      } else {
        System.out.println("下载失败: " + resp.code());
      }
    }
  }
}

C#（HttpClient）：

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

class Program {
  static async Task Main() {
    var url = "https://www.clipimg.com/api/idphoto/download/{img_name}";
    var apiKey = "YOUR_API_KEY";

    using var http = new HttpClient();
    var req = new HttpRequestMessage(HttpMethod.Post, url);
    req.Headers.Add("X-API-Key", apiKey);
    
    var resp = await http.SendAsync(req);
    if (resp.IsSuccessStatusCode) {
        var bytes = await resp.Content.ReadAsByteArrayAsync();
        await File.WriteAllBytesAsync("output.jpg", bytes);
        Console.WriteLine("下载成功");
    } else {
        Console.WriteLine($"下载失败: {resp.StatusCode}");
    }
  }
}

状态码说明 #

状态码	说明
0	成功
400	参数错误
401	暂不支持你上传的照片格式
402	您的API点数已用完，请及时充值
407	未识别到人脸，请确保面部清晰可见，光线充足，并正对摄像头
408	检测到多人，请确保照片中仅包含一人
409	检测到人脸占用了整张图片且超出了图片边界，请保持适当距离重新拍摄
413	人脸未正对摄像头，请保持面部正对镜头重新拍摄
416	处理超时，请稍后再试
417	图片中人脸过大，无法制作该规格的证件照（含细分提示）
433	人脸关键点检测失败，请更换照片后重新尝试

错误码详细说明 #

400 参数错误：缺少或非法参数（如 file/width/height 未提供或越界），或文件读取失败；请按文档校验入参。
401 暂不支持你上传的照片格式：图片编码不被支持或文件损坏；请更换为常见格式（JPG/PNG）且文件完整。
402 您的API点数已用完，请及时充值：账户余额不足，无法进行下载无水印图片等扣费操作。
407 未识别到人脸…：无法定位有效人脸；请确保面部清晰可见，光线充足，并正对摄像头。
408 检测到多人…：检测到多人脸；请确保照片中仅包含一人。
409 检测到人脸占用了整张图片…：人脸区域过大或离镜头过近，超出了图片边界；请保持适当距离重新拍摄。
413 人脸未正对摄像头…：人脸角度偏差过大；请保持面部正对镜头重新拍摄。
416 处理超时，请稍后再试：处理耗时超出限制；可重试或压缩图片后再试。
417 图片中人脸过大…：在人脸比例上限下仍无法满足目标规格。该错误码包含以下细分提示，请根据具体提示调整：
- 人脸在画面中占比过大（脸宽超出最大比例），请远离镜头或留白更多
- 头部高度占比过大，请远离镜头或留白更多
- 双眼间距占比过大（距离镜头过近），请远离镜头或留白更多
- 裁剪范围超出图片边界（留白不足），请远离镜头或更换边距更大的照片
- 图片中人脸过大，无法制作该规格的证件照，请保持适当距离重新拍摄
433 人脸关键点检测失败…：人脸关键点解析失败，请更换照片后重新尝试。

提示：402 API点数不足通常发生在下载无水印图片时，非制作错误。

图片访问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 接口：调用不消耗点数；下载“无水印原图”扣 30 点/次；下载“无水印排版照”扣 50 点/次。
/check 接口：调用即扣 1 点/次（独立检测收费）。
/make_and_check 接口：调用不消耗点数；下载“无水印原图”扣 50 点/次；下载“无水印排版照”扣 50 点/次。

结果保留说明 #

制作结果保留1小时，1小时后自动删除制作结果图片，请及时保存。重复下载同一张照片不会重复扣费。

典型场景参数 #

1. 基础证件照制作 #

仅提供基础参数，适合一般用户：

{
  "width": 295,
  "height": 413,
  "fair_level": 0.3
}

2. 自定义规格证件照 #

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

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

开发建议 #

错误处理: 建议对各种状态码进行完整的错误处理
参数校验: 在发送请求前对参数进行本地校验
图片优化: 建议在上传前对图片进行适当压缩
缓存策略: 可以缓存制作成功的图片，避免重复制作

使用代码实现证件照排版 #

您可以使用代码对下载后的证件照实现排版，以节省成本！

Python 示例 #

from PIL import Image, ImageDraw

# 6 寸相纸尺寸（英寸）
SIX_INCH_WIDTH = 6.0
SIX_INCH_HEIGHT = 4.0
# 默认分辨率（dpi）
DEFAULT_DPI = 300
# 照片间空隙（像素）
GAP = 10
# 裁剪线颜色
CUTLINE_COLOR = (0, 0, 0)
# 裁剪线宽度
CUTLINE_WIDTH = 1

# 转换为像素
SIX_INCH_PIXEL_WIDTH = int(SIX_INCH_WIDTH * DEFAULT_DPI)
SIX_INCH_PIXEL_HEIGHT = int(SIX_INCH_HEIGHT * DEFAULT_DPI)


def layout_photos(photo_path, output_path):
    # 打开照片
    photo = Image.open(photo_path)
    photo_width, photo_height = photo.size
    try:
        photo_dpi = photo.info['dpi'][0]
        if photo_dpi == 0:
            photo_dpi = DEFAULT_DPI
    except KeyError:
        photo_dpi = DEFAULT_DPI

    # 计算照片实际打印尺寸（英寸）
    photo_print_width = photo_width / photo_dpi
    photo_print_height = photo_height / photo_dpi

    # 转换为像素（使用默认 dpi）
    photo_pixel_width = int(photo_print_width * DEFAULT_DPI)
    photo_pixel_height = int(photo_print_height * DEFAULT_DPI)

    # 调整照片大小
    resized_photo = photo.resize((photo_pixel_width, photo_pixel_height))

    # 创建相纸
    paper = Image.new('RGB', (SIX_INCH_PIXEL_WIDTH, SIX_INCH_PIXEL_HEIGHT), 'white')
    draw = ImageDraw.Draw(paper)

    # 计算每行和每列可放置的照片数量
    cols = (SIX_INCH_PIXEL_WIDTH + GAP) // (photo_pixel_width + GAP)
    rows = (SIX_INCH_PIXEL_HEIGHT + GAP) // (photo_pixel_height + GAP)

    # 计算排版的总宽度和高度
    total_width = cols * photo_pixel_width + (cols - 1) * GAP
    total_height = rows * photo_pixel_height + (rows - 1) * GAP

    # 计算居中偏移量
    start_x = (SIX_INCH_PIXEL_WIDTH - total_width) // 2
    start_y = (SIX_INCH_PIXEL_HEIGHT - total_height) // 2

    # 粘贴照片
    for i in range(rows):
        for j in range(cols):
            x = start_x + j * (photo_pixel_width + GAP)
            y = start_y + i * (photo_pixel_height + GAP)
            paper.paste(resized_photo, (x, y))

    # 绘制垂直裁剪线（间隙两边）
    for j in range(cols + 1):
        if j == 0:
            left_x1 = start_x
            draw.line((left_x1, 0, left_x1, start_y), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((left_x1, start_y + total_height, left_x1, SIX_INCH_PIXEL_HEIGHT), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
        elif j == cols:
            left_x2 = start_x + total_width
            draw.line((left_x2, 0, left_x2, start_y), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((left_x2, start_y + total_height, left_x2, SIX_INCH_PIXEL_HEIGHT), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
        else:
            left_x1 = start_x + (j - 1) * (photo_pixel_width + GAP) + photo_pixel_width
            left_x2 = left_x1 + GAP
            draw.line((left_x1, 0, left_x1, start_y), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((left_x1, start_y + total_height, left_x1, SIX_INCH_PIXEL_HEIGHT), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((left_x2, 0, left_x2, start_y), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((left_x2, start_y + total_height, left_x2, SIX_INCH_PIXEL_HEIGHT), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)

    # 绘制水平裁剪线（间隙两边）
    for i in range(rows + 1):
        if i == 0:
            top_y1 = start_y
            draw.line((0, top_y1, start_x, top_y1), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((start_x + total_width, top_y1, SIX_INCH_PIXEL_WIDTH, top_y1), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
        elif i == rows:
            top_y2 = start_y + total_height
            draw.line((0, top_y2, start_x, top_y2), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((start_x + total_width, top_y2, SIX_INCH_PIXEL_WIDTH, top_y2), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
        else:
            top_y1 = start_y + (i - 1) * (photo_pixel_height + GAP) + photo_pixel_height
            top_y2 = top_y1 + GAP
            draw.line((0, top_y1, start_x, top_y1), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((start_x + total_width, top_y1, SIX_INCH_PIXEL_WIDTH, top_y1), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((0, top_y2, start_x, top_y2), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)
            draw.line((start_x + total_width, top_y2, SIX_INCH_PIXEL_WIDTH, top_y2), fill=CUTLINE_COLOR, width=CUTLINE_WIDTH)

    paper.save(output_path)


# 示例调用
# layout_photos('your_photo.jpg', 'layout_photo.jpg')

使用代码给证件照添加自定义文字 #

补充说明：在证件照预览\下载、排版照预览\下载、换装照预览\下载接口添加参数text=自定义文字，可实现对证件照添加自定义文字的功能，但是建议开发者自己使用代码添加文字更具灵活性，后期可能会下线该功能，推荐使用以下代码实现。

参数名: text
类型: string
必填: 否
说明: 自定义文字内容。若传入该参数，系统将在图片底部增加白色背景区域，并将文字居中绘制在其中。

支持接口与行为细节:

证件照预览/下载
- 对应接口地址: /idphoto/preview/{preview_img_name}, /idphoto/download/{img_name}
- 行为: 在生成的单张证件照底部添加自定义文字。
排版照预览/下载
- 对应接口地址: /idphoto/print_preview/{preview_print_img_name}, /idphoto/print_download/{print_img_name}
- 行为: 先添加文字，后排版。即先在单张证件照底部添加文字，然后再将带有文字的照片进行排版组合。最终生成的排版照中，每一张小照片底部都会包含该文字。
换装照预览/下载
- 对应接口地址: /idphoto/change_clothes/preview/{preview_img_name}, /idphoto/change_clothes/download/{img_name}
- 行为: 在换装完成后的证件照底部添加自定义文字。

调用方式:

GET 请求 (预览接口): 拼接在 URL 参数中，需进行 URL 编码。
- 示例: .../preview/xxx.jpg?text=%E5%BC%A0%E4%B8%89
POST 请求 (下载接口): 包含在 JSON 请求体中。
- 示例: {"text": "张三", ...}

您可以使用代码给证件照底部添加自定义文字（例如姓名、身份证号等）。

Python 示例 #

from PIL import Image, ImageDraw, ImageFont
import math

def add_text_to_image(image_path, output_path, text):
    # 打开图片
    img = Image.open(image_path)
    img_width, img_height = img.size
    
    # 加载字体 (请确保系统中有该字体文件，或指定字体路径)
    # 字体大小根据图片高度动态计算，约为高度的 1/24
    font_size = math.ceil(img_height / 24)
    try:
        # Windows系统通常有 SimHei.ttf，Linux可能需要指定其他中文字体路径
        font = ImageFont.truetype('SimHei.ttf', font_size)
    except IOError:
        print("未找到 SimHei.ttf，尝试使用默认字体")
        font = ImageFont.load_default()
        
    # 计算文字宽高
    bbox = font.getbbox(text)
    text_width = bbox[2]
    text_height = bbox[3]

    # 创建新的背景图，高度增加以容纳文字 (文字高度 + 6像素间距)
    new_height = img_height + text_height + 6
    # 创建白底背景
    new_img = Image.new("RGB", (img_width, new_height), "white")
    
    # 将原图粘贴到顶部
    new_img.paste(img, (0, 0))
    
    draw = ImageDraw.Draw(new_img)
    
    # 计算文字居中位置
    x = math.ceil((img_width - text_width) / 2)
    y = img_height + 3
    
    # 绘制文字 (黑色)
    draw.text((x, y), text, fill=(0, 0, 0), font=font)
    
    # 保存图片
    new_img.save(output_path)

# 示例调用
# add_text_to_image('idphoto.jpg', 'idphoto_with_text.jpg', '张三 110101199001011234')

证件照规格列表 #

如需全部规格列表数据，请咨询客服获取。

id	name
1	一寸
2	小一寸
3	大一寸
4	二寸
5	小二寸
6	三寸
7	五寸
8	国考（二寸）(35*45mm)
9	英语四六级考试（144×192，0~10kb）(12*16mm)
10	全国计算机等级考试(12*16mm)

接口概述 #

典型使用场景 #

请求格式 #

Headers #

请求体参数 #

必须参数

图片输入（二选一）

制作参数

人脸比例参数

位置参数

基础检测参数（用于制作时的筛选）

背景颜色配置格式 #

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

请求示例 #

响应格式 #

成功响应 #

错误响应 #

各语言调用示例 #

curl #

使用 file_url 输入（可选）

Python（requests） #

Node.js（axios） #

PHP（cURL 扩展） #

Java（OkHttp） #

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

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

状态码说明 #

错误码详细说明 #

图片访问URL #

预览图片 #

下载图片 #

扣点规则说明 #

API点数消耗规则 #

结果保留说明 #

典型场景参数 #

1. 基础证件照制作 #

2. 自定义规格证件照 #

开发建议 #

使用代码实现证件照排版 #

Python 示例 #

使用代码给证件照添加自定义文字 #

Python 示例 #

证件照规格列表 #

相关推荐 #