중복 찾기

여러 이미지를 업로드하여 지각적 해싱(dHash)으로 중복 및 유사 중복 이미지를 감지합니다. 유사한 이미지를 그룹으로 묶고, 각 그룹에서 가장 품질이 좋은 버전을 식별하며, 절약 가능한 공간을 계산합니다.

API 엔드포인트

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

여러 이미지 파일과 선택적 JSON settings 필드가 포함된 multipart 폼 데이터를 받습니다.

파라미터

파라미터	타입	필수	기본값	설명
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비트 열)를 사용합니다. 크기 조정, 재압축, 사소한 편집을 거친 경우에도 중복을 잡아냅니다.
• threshold는 해시 간 최대 해밍 거리를 나타냅니다. 기본값 8은 오탐을 피하면서 유사 중복을 잡아냅니다. 픽셀 단위로 동일한 것만 찾으려면 0을, 매우 느슨한 매칭에는 15-20을 사용하세요.
• 각 그룹에서 "최적" 이미지는 픽셀 수(너비 x 높이)가 가장 많은 것이며, 동점일 경우 파일 크기로 결정합니다.
• 최소 2개의 이미지가 필요합니다. 검증 또는 디코딩에 실패한 파일은 전체 요청을 실패시키지 않고 skippedFiles에 보고됩니다.
• 썸네일은 데이터 URI로 인코딩된 너비 200px JPEG 미리보기입니다.
• 모든 일반 형식이 지원됩니다(HEIC, RAW, PSD, SVG는 자동으로 디코딩됨).