查找重复项

上传多张图像，使用感知哈希（dHash）检测重复和近似重复的图像。将相似图像分组，识别每组中质量最佳的版本，并计算可节省的潜在空间。

API 端点

POST /api/v1/tools/image/find-duplicates

接受包含多个图像文件的 multipart 表单数据，以及一个可选的 JSON settings 字段。

参数

参数	类型	是否必填	默认值	说明
threshold	number	否	8	将图像视为重复项的最大汉明距离（0 到 20）。值越小匹配越严格

文件字段

在 multipart 请求中上传至少 2 个图像文件（全部使用 file 字段名，或对文件部分使用任意字段名）。

请求示例

curl -X POST http://localhost:1349/api/v1/tools/image/find-duplicates \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"threshold": 8}'

响应示例

{
  "totalImages": 4,
  "duplicateGroups": [
    {
      "groupId": 1,
      "files": [
        {
          "filename": "photo1.jpg",
          "similarity": 100,
          "width": 4032,
          "height": 3024,
          "fileSize": 2450000,
          "format": "jpeg",
          "isBest": true,
          "thumbnail": "data:image/jpeg;base64,/9j/..."
        },
        {
          "filename": "photo2.jpg",
          "similarity": 96.88,
          "width": 1920,
          "height": 1440,
          "fileSize": 850000,
          "format": "jpeg",
          "isBest": false,
          "thumbnail": "data:image/jpeg;base64,/9j/..."
        }
      ]
    }
  ],
  "uniqueImages": 2,
  "spaceSaveable": 850000,
  "skippedFiles": []
}

响应字段

字段	类型	说明
totalImages	number	成功分析的图像数量
duplicateGroups	array	重复图像的分组
uniqueImages	number	不属于任何重复分组的图像数量
spaceSaveable	number	移除非最佳重复项后可节省的总字节数
skippedFiles	array	无法处理的文件（含文件名和原因）

重复分组对象

字段	类型	说明
groupId	number	分组标识符
files	array	此重复分组中的图像

文件对象（分组内）

字段	类型	说明
filename	string	原始文件名
similarity	number	与参考图像（分组中的第一张）的相似度百分比
width	number	图像宽度（像素）
height	number	图像高度（像素）
fileSize	number	文件大小（字节）
format	string	图像格式
isBest	boolean	是否为质量最高的版本（像素最多、文件最大）
thumbnail	string 或 null	用于预览的 Base64 JPEG 缩略图（200px 宽）

说明

• 使用 128 位 dHash（64 位行 + 64 位列）进行感知相似度检测。即使经过缩放、重新压缩和轻微编辑，也能识别出重复项。
• 阈值表示两个哈希之间的最大汉明距离。默认值 8 可捕获近似重复项，同时避免误报。使用 0 表示仅识别像素完全相同的图像，使用 15-20 表示非常宽松的匹配。
• 每组中的“最佳”图像是像素最多（宽 x 高）的那张，以文件大小作为决胜依据。
• 至少需要 2 张图像。验证或解码失败的文件会在 skippedFiles 中报告，而不会导致整个请求失败。
• 缩略图是编码为 data URI 的 200px 宽 JPEG 预览图。
• 支持所有常见格式（HEIC、RAW、PSD、SVG 会被自动解码）。