证件照换装API接口文档 - 智能识别身形/一键换正装

可立图 ClipImg 证件照换装 API 服务

接口概述 #

本接口提供专业的证件照智能换装服务，支持对用户上传的证件照或已通过制作接口生成的证件照进行服装替换。接口采用先进的图像融合技术，能够自动调整服装的大小、角度和光影，使其与人物颈部自然衔接，生成逼真的换装效果。

重要提示：本接口专注于“换装”功能，不提供抠图/去背景服务。输入图片必须是已经处理好的纯色背景或渐变色背景证件照。如果需要从生活照制作证件照并换装，请先调用证件照制作接口或证件照制作并检测接口。

典型使用场景 #

求职招聘：将休闲风格的证件照快速转换为穿着正装的职业形象照，提升简历专业度。
公务/考试报名：满足各类考试（如公务员、教资）或证件办理对着装（如深色正装、有领衣服）的特定要求。
校园/企业采集：统一学生或员工的证件照着装风格，无需全员现场更换服装拍摄。
照相馆/图文店：为顾客提供低成本的“云换装”增值服务，丰富产品线。

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

请求格式 #

Headers #

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

请求体参数 #

图片输入（二选一）

参数	类型	说明
file	string	Base64 编码的图片数据（不包含base64头部）。仅支持纯色背景图片，并需使用 `bg_color` 指定色值。若未提供 `img_name` 则必选。注意：使用file参数时，必须传入标准的纯色背景证件照照片，否则可能影响换装效果
img_name	string	已存在的证件照图片名称（如证件照制作 `/idphoto/make` 或证件照制作+检测 `/idphoto/make_and_check` 生成的 `img_name`）。若提供此参数，则优先使用该图片进行换装。推荐使用此方式，效果会更好。注意：仍需指定 `bg_color`

必须参数

参数	类型	说明
clothes_id	int	服装ID。请参考换装列表或自定义服装ID
bg_color	string	指定证件照图片的背景色，16进制表示，例如：`#02A7F0`

可选参数

参数	类型	默认值	说明
enc_color	string	null	背景渐变色结束色值（Hex）。不传值时为纯色背景
file_format	int	0	输出格式（0:PNG，1:JPG）
custom	int	0	是否使用自定义服装（0:系统服装，1:自定义服装）。自定义服装ID请前往API管理上传获取
watermark_id	int	null	自定义水印id，需要在API管理上传

换装列表 #

下载缩略图压缩包（1-16男装、17-32女装、33-48童装）

服装文件下载

响应格式 #

成功响应 #

{
  "code": 0,
  "msg": "Success",
  "data": {
    "download_url": "https://www.clipimg.com/api/idphoto/change_clothes/download/...",
    "preview_url": "https://www.clipimg.com/api/idphoto/change_clothes/preview/...",
    "img_name": "9ad..._changeCloth",
    "preview_img_name": "9ad..._changeCloth_preview",
    "print_img_name": "9ad..._changeCloth_print",
    "print_url": "https://www.clipimg.com/api/idphoto/print_download/...",
    "preview_print_url": "https://www.clipimg.com/api/idphoto/print_preview/...",
    "preview_print_img_name": "9ad..._changeCloth_print_preview"
  }
}

错误响应 #

{
  "code": 410,
  "msg": "未检测到人脸",
  "data": []
}

状态码说明 #

状态码	说明
0	成功
400	参数错误
402	您的API点数已用完，请及时充值
404	img_name对应的原始文件不存或已过期
410	未检测到人脸
411	换装须要尽量露出脖子
415	换装异常
416	处理超时，请稍后再试
433	人脸关键点解析失败，请更换照片后重新尝试

图片访问URL #

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

预览图片 #

换装照预览: /idphoto/change_clothes/preview/{preview_img_name}

下载图片 #

换装照下载: /idphoto/change_clothes/download/{img_name}
- 请求方式: POST
- Header: X-API-Key, Content-Type: application/json
- 计费: 调用成功扣除API账户30点余额

扣点规则说明 #

/change_clothes 接口：调用不产生费用。
下载接口：下载无水印图片扣 30 点/次；下载无水印换装排版照扣 100 点/次。
结果保留：制作结果保留1小时，1小时后自动删除，请及时保存。重复下载同一张照片不会重复扣费。

各语言调用示例 #

curl #

curl -X POST "https://www.clipimg.com/api/idphoto/change_clothes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "BASE64_IMAGE_DATA",
    "clothes_id": 1,
    "bg_color": "#FFFFFF",
    "file_format": 1
  }'

Python (requests) #

import base64, json, requests

api = "https://www.clipimg.com/api/idphoto/change_clothes"
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,
    "clothes_id": 1,
    "bg_color": "#FFFFFF",
    "file_format": 1
}

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

Node.js (axios) #

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/change_clothes', {
    file: imageBase64,
    clothes_id: 1,
    bg_color: '#FFFFFF',
    file_format: 1
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch(error => {
    console.error(error.response ? error.response.data : error.message);
});

PHP (cURL) #

<?php
$apiKey = 'YOUR_API_KEY';
$imagePath = 'photo.jpg';
$imageBase64 = base64_encode(file_get_contents($imagePath));

$data = [
    'file' => $imageBase64,
    'clothes_id' => 1,
    'bg_color' => '#FFFFFF',
    'file_format' => 1
];

$ch = curl_init('https://www.clipimg.com/api/idphoto/change_clothes');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

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

echo "HTTP Code: $httpCode\n";
echo $response;
?>

Java (OkHttp) #

import okhttp3.*;
import java.io.File;
import java.nio.file.Files;
import java.util.Base64;

public class ChangeClothesDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        File file = new File("photo.jpg");
        byte[] fileContent = Files.readAllBytes(file.toPath());
        String imageBase64 = Base64.getEncoder().encodeToString(fileContent);

        String json = "{"
                + "\"file\": \"" + imageBase64 + "\","
                + "\"clothes_id\": 1,"
                + "\"bg_color\": \"#FFFFFF\","
                + "\"file_format\": 1"
                + "}";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);
        Request request = new Request.Builder()
                .url("https://www.clipimg.com/api/idphoto/change_clothes")
                .addHeader("X-API-Key", apiKey)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

C# (HttpClient) #

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

class Program
{
    static async Task Main(string[] args)
    {
        var apiKey = "YOUR_API_KEY";
        var imagePath = "photo.jpg";
        var imageBase64 = Convert.ToBase64String(File.ReadAllBytes(imagePath));

        var json = $@"{{
            ""file"": ""{imageBase64}"",
            ""clothes_id"": 1,
            ""bg_color"": ""#FFFFFF"",
            ""file_format"": 1
        }}";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            
            var response = await client.PostAsync("https://www.clipimg.com/api/idphoto/change_clothes", content);
            var result = await response.Content.ReadAsStringAsync();
            
            Console.WriteLine(result);
        }
    }
}

可立图API文档

证件照换装API文档