Поиск дубликатов

Загрузите несколько изображений для обнаружения дубликатов и почти-дубликатов с помощью перцептивного хеширования (dHash). Группирует похожие изображения, определяет версию наилучшего качества в каждой группе и рассчитывает потенциальную экономию места.

Конечная точка API

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

Принимает данные формы multipart с несколькими файлами изображений и необязательным полем JSON settings.

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
threshold	number	Нет	8	Максимальное расстояние Хэмминга, при котором изображения считаются дубликатами (от 0 до 20). Меньше = строже сопоставление

Поля файлов

Загрузите не менее 2 файлов изображений в запросе multipart (все с именем поля 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, а не приводят к сбою всего запроса.
• Миниатюры представляют собой JPEG-превью шириной 200px, закодированные как data URI.
• Поддерживаются все распространённые форматы (HEIC, RAW, PSD, SVG декодируются автоматически).