尋找重複項

上傳多張圖片，使用感知雜湊（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 位元欄）進行感知相似度偵測。即使經過縮放、重新壓縮與細微編輯，也能偵測出重複項。
• threshold 代表雜湊之間的最大漢明距離。預設值 8 可偵測近似重複項，同時避免誤判。使用 0 只比對像素完全相同者，或使用 15-20 進行非常寬鬆的比對。
• 每組中的「最佳」圖片是像素最多者（寬 x 高），並以檔案大小作為決勝條件。
• 至少需要 2 張圖片。驗證或解碼失敗的檔案會回報於 skippedFiles 中，而不會導致整個請求失敗。
• 縮圖是寬 200px 的 JPEG 預覽，編碼為 data URI。
• 支援所有常見格式（HEIC、RAW、PSD、SVG 會自動解碼）。