feat(docs-i18n): translate all documentation into 20 languages

All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,438 @@
+---
+description: "Довідник рушія ШІ з усіма локальними інструментами ML. Видалення фону, збільшення роздільної здатності, OCR, розпізнавання облич, реставрація фото та інше."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: e36cdc2779d7
+---
+
+# Довідник рушія ШІ {#ai-engine-reference}
+
+Пакет `@snapotter/ai` з'єднує Node.js із **постійним допоміжним процесом Python** для всіх операцій ML. Процес диспетчера залишається активним між запитами задля швидкого «теплого» старту. NVIDIA CUDA автоматично визначається під час запуску та використовується за наявності; в іншому разі інструменти ШІ працюють на CPU.
+
+Прискорення на iGPU Intel/AMD через VA-API, Quick Sync або OpenCL наразі не підтримується для інференсу ШІ. Прокидання `/dev/dri` в контейнер не прискорює ці інструменти допоміжного процесу Python, якщо немає NVIDIA GPU з підтримкою CUDA.
+
+19 інструментів ШІ на допоміжному процесі Python у чотирьох модальностях (зображення, аудіо, відео, документ), а також 2 інструменти з необов'язковими можливостями ШІ. Усі моделі працюють локально: після початкового завантаження моделі інтернет не потрібен.
+
+## Архітектура {#architecture}
+
+```
+Node.js Tool Route
+      |
+      v
+ @snapotter/ai bridge.ts
+      | (stdin/stdout JSON + stderr progress events)
+      v
+ Python dispatcher (persistent process, "ai" profile)
+      |
+      |-- remove_bg.py        (rembg / BiRefNet)
+      |-- upscale.py          (RealESRGAN)
+      |-- inpaint.py          (LaMa ONNX)
+      |-- outpaint.py         (LaMa canvas expansion)
+      |-- ocr.py              (PaddleOCR / Tesseract)
+      |-- ocr_pdf.py          (page-by-page document OCR)
+      |-- ocr_preprocess.py   (image enhancement for OCR)
+      |-- detect_faces.py     (MediaPipe)
+      |-- face_landmarks.py   (MediaPipe landmarks)
+      |-- enhance_faces.py    (GFPGAN / CodeFormer)
+      |-- colorize.py         (DDColor)
+      |-- noise_removal.py    (SCUNet / tiered denoising)
+      |-- red_eye_removal.py  (landmark + color analysis)
+      |-- restore.py          (scratch repair + enhancement + denoising)
+      |-- transcribe.py       (faster-whisper speech-to-text)
+      +-- install_feature.py  (on-demand bundle installer)
+```
+
+Окремий профіль диспетчера «docs» замінює список дозволених ШІ на скрипти обробки документів (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) і пропускає важкі імпорти ML.
+
+**Тайм-аути:** 300 с за замовчуванням; OCR та видалення фону BiRefNet отримують 600 с.
+
+## Набори функцій {#feature-bundles}
+
+Моделі ШІ пакуються за спільним стеком залежностей, а не по одному архіву на інструмент. Набір функцій може вмикати декілька інструментів, коли вони використовують одну родину моделей, Python-колеса або нативні бібліотеки. Це зменшує розмір релізного Docker-образу й уникає зберігання дублікатів тих самих моделей матування фону, розпізнавання облич, OCR, реставрації та мовлення.
+
+Docker-образ постачає застосунок разом зі спільним середовищем виконання. Великі архіви моделей завантажуються за потреби в постійний том `/data/ai`, а далі повторно використовуються кожним інструментом, якому вони потрібні. Якщо набір уже встановлено, бо його потребував інший інструмент, увімкнення нового залежного інструмента не завантажує цей набір повторно.
+
+Кожен інструмент ШІ вимагає одного чи кількох наборів функцій, перш ніж зможе працювати. Адмін-інтерфейс встановлює за інструментом через `POST /api/v1/admin/tools/:toolId/features/install`, який розкриває повний список наборів, пропускає вже встановлені набори та ставить у чергу лише відсутні завантаження. Наприклад, увімкнення Passport Photo на новому екземплярі ставить у чергу `background-removal` і `face-detection`; увімкнення його після того, як уже встановлено Background Removal, ставить у чергу лише `face-detection`.
+
+| Набір | Розмір | Група спільних залежностей | Інструменти, що його використовують |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 ГБ | матування фону rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 МБ | розпізнавання облич і орієнтирів MediaPipe | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 ГБ | inpainting/outpainting LaMa та DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 ГБ | RealESRGAN, GFPGAN / CodeFormer, шумозаглушення | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 ГБ | конвеєр ремонту подряпин і реставрації | restore-photo |
+| `ocr` | 5-6 ГБ | стек OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `transcription` | ~600 МБ | моделі мовлення в текст faster-whisper | transcribe-audio, auto-subtitles |
+
+Інструменти з міжнабірними залежностями:
+
+| Інструмент | Потрібні набори | Чому |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | Видаляє фон, а потім за орієнтирами обличчя кадрує кроп під правила фото на паспорт та ID. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | Розпізнає обличчя перед запуском покращення GFPGAN або CodeFormer на вибраних областях облич. |
+
+Інструмент доступний лише тоді, коли встановлено всі потрібні йому набори. Часткові встановлення є коректними та обробляються поетапно: встановлені набори повторно використовуються, відсутні набори показуються як завантаження, а поставлені в чергу встановлення виконуються по одному, щоб спільне середовище Python не змінювалося одночасно.
+
+---
+
+## Видалення фону {#background-removal}
+
+**Маршрут інструмента:** `remove-background`  
+**Модель:** rembg з BiRefNet (за замовчуванням) або варіанти U2-Net
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `model` | string | - | Варіант моделі (необов'язкове перевизначення) |
+| `backgroundType` | string | `"transparent"` | Один з: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | Hex-колір суцільного фону |
+| `gradientColor1` | string | - | Перший колір градієнта |
+| `gradientColor2` | string | - | Другий колір градієнта |
+| `gradientAngle` | number | - | Кут градієнта в градусах |
+| `blurEnabled` | boolean | - | Увімкнути ефект розмиття фону |
+| `blurIntensity` | number (0-100) | - | Інтенсивність розмиття |
+| `shadowEnabled` | boolean | - | Увімкнути падаючу тінь на об'єкті |
+| `shadowOpacity` | number (0-100) | - | Непрозорість тіні |
+| `outputFormat` | string | - | Формат виводу: `png`, `webp` або `avif` |
+| `edgeRefine` | integer (0-3) | - | Рівень уточнення країв |
+| `decontaminate` | boolean | - | Прибрати перетікання кольору з країв |
+
+## Заміна фону {#background-replace}
+
+**Маршрут інструмента:** `background-replace`  
+**Модель:** rembg / BiRefNet (спільна з remove-background)
+
+Видаляє фон і замінює його суцільним кольором або градієнтом.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Режим фону |
+| `color` | string | `"#ffffff"` | Hex-колір фону (коли `backgroundType` дорівнює `color`) |
+| `gradientColor1` | string | - | Перший hex-колір градієнта |
+| `gradientColor2` | string | - | Другий hex-колір градієнта |
+| `gradientAngle` | integer (0-360) | `180` | Кут градієнта в градусах |
+| `feather` | integer (0-20) | `0` | Радіус розтушовування країв |
+| `format` | `"png"` \| `"webp"` | `"png"` | Формат виводу |
+
+## Розмиття фону {#blur-background}
+
+**Маршрут інструмента:** `blur-background`  
+**Модель:** rembg / BiRefNet (спільна з remove-background)
+
+Розмиває фон, зберігаючи об'єкт чітким.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | Інтенсивність розмиття |
+| `feather` | integer (0-20) | `0` | Радіус розтушовування країв |
+| `format` | `"png"` \| `"webp"` | `"png"` | Формат виводу |
+
+## Збільшення роздільної здатності зображення {#image-upscaling}
+
+**Маршрут інструмента:** `upscale`  
+**Модель:** RealESRGAN (з резервним Lanczos за недоступності)
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | Коефіцієнт збільшення |
+| `model` | string | `"auto"` | Варіант моделі |
+| `faceEnhance` | boolean | `false` | Застосувати прохід покращення облич GFPGAN |
+| `denoise` | number | `0` | Сила шумозаглушення |
+| `format` | string | `"auto"` | Перевизначення формату виводу |
+| `quality` | number | `95` | Якість виводу (1-100) |
+
+## OCR / Витяг тексту {#ocr-text-extraction}
+
+**Маршрут інструмента:** `ocr`  
+**Моделі:** Tesseract (швидко), PaddleOCR PP-OCRv5 (збалансовано), PaddleOCR-VL 1.5 (найкраще)
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Рівень обробки |
+| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | Попередньо обробити зображення для підвищення точності OCR |
+| `engine` | string | - | Застаріле. Зіставляє `tesseract` з `fast`, `paddleocr` з `balanced` |
+
+Повертає структуровані результати з обмежувальними рамками, оцінками впевненості та витягнутими блоками тексту.
+
+## OCR для PDF {#pdf-ocr}
+
+**Маршрут інструмента:** `ocr-pdf`  
+**Моделі:** Та сама система рівнів, що й для OCR зображень
+
+Витягає текст зі сканованих PDF-документів за допомогою OCR на базі ШІ, сторінка за сторінкою.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Рівень обробки |
+| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | Вибір сторінок: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## Розмиття облич / PII {#face-pii-blur}
+
+**Маршрут інструмента:** `blur-faces`  
+**Модель:** розпізнавання облич MediaPipe
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | Радіус гаусового розмиття |
+| `sensitivity` | number (0-1) | `0.5` | Поріг впевненості розпізнавання |
+
+## Покращення облич {#face-enhancement}
+
+**Маршрут інструмента:** `enhance-faces`  
+**Моделі:** GFPGAN, CodeFormer
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Модель покращення |
+| `strength` | number (0-1) | `0.8` | Сила покращення |
+| `sensitivity` | number (0-1) | `0.5` | Поріг розпізнавання облич |
+| `onlyCenterFace` | boolean | `false` | Покращувати лише найцентральніше обличчя |
+
+## Колоризація ШІ {#ai-colorization}
+
+**Маршрут інструмента:** `colorize`  
+**Модель:** DDColor (з резервним OpenCV DNN)
+
+Перетворює чорно-білі або відтінково-сірі фото на повнокольорові.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | Сила насиченості кольору |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Варіант моделі |
+
+## Видалення шуму {#noise-removal}
+
+**Маршрут інструмента:** `noise-removal`  
+**Модель:** SCUNet (багаторівневий конвеєр шумозаглушення)
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Рівень обробки |
+| `strength` | number (0-100) | `50` | Сила шумозаглушення |
+| `detailPreservation` | number (0-100) | `50` | Скільки деталей зберегти; вище означає більше текстури |
+| `colorNoise` | number (0-100) | `30` | Сила зменшення колірного шуму |
+| `format` | string | `"original"` | Формат виводу: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | Якість кодування виводу |
+
+## Видалення ефекту червоних очей {#red-eye-removal}
+
+**Маршрут інструмента:** `red-eye-removal`
+
+Розпізнає орієнтири обличчя, локалізує області очей і виправляє перенасичення червоного каналу.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | Поріг розпізнавання червоних пікселів |
+| `strength` | number (0-100) | `70` | Сила корекції |
+| `format` | string | - | Перевизначення формату виводу (необов'язкове) |
+| `quality` | number (1-100) | `90` | Якість виводу |
+
+## Реставрація фото {#photo-restoration}
+
+**Маршрут інструмента:** `restore-photo`
+
+Багатоетапний конвеєр для старих або пошкоджених фото: розпізнавання й ремонт подряпин/розривів, покращення облич, шумозаглушення та необов'язкова колоризація.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | Розпізнати та відремонтувати подряпини, розриви |
+| `faceEnhancement` | boolean | `true` | Застосувати прохід покращення облич |
+| `fidelity` | number (0-1) | `0.7` | Сила покращення облич (вище = консервативніше) |
+| `denoise` | boolean | `true` | Застосувати прохід шумозаглушення |
+| `denoiseStrength` | number (0-100) | `25` | Сила шумозаглушення |
+| `colorize` | boolean | `false` | Колоризувати після реставрації |
+| `colorizeStrength` | number (0-100) | `85` | Інтенсивність колоризації |
+
+## Фото на паспорт {#passport-photo}
+
+**Маршрут інструмента:** `passport-photo`  
+**Моделі:** орієнтири обличчя MediaPipe + видалення фону BiRefNet
+
+Двофазний робочий процес: аналіз (розпізнати обличчя + видалити фон), потім генерація (кроп, зміна розміру, розкладка). Підтримує 37+ країн у 6 регіонах.
+
+### Фаза 1: Аналіз {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+Приймає файл зображення (multipart). Повертає дані орієнтирів обличчя, попередній перегляд у base64 та розміри зображення.
+
+### Фаза 2: Генерація {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+Приймає тіло JSON із результатами Фази 1 плюс налаштування генерації:
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `jobId` | string | (обов'язково) | ID завдання з Фази 1 |
+| `filename` | string | (обов'язково) | Оригінальне ім'я файлу з Фази 1 |
+| `countryCode` | string | (обов'язково) | Код країни ISO (напр., `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | Тип документа |
+| `bgColor` | string | `"#FFFFFF"` | Hex кольору фону |
+| `printLayout` | string | `"none"` | Розкладка друку: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | Макс. розмір файлу в КБ (0 = без обмеження) |
+| `dpi` | number (72-1200) | `300` | DPI виводу |
+| `customWidthMm` | number | - | Власна ширина в мм (перевизначає специфікацію країни) |
+| `customHeightMm` | number | - | Власна висота в мм (перевизначає специфікацію країни) |
+| `zoom` | number (0.5-3) | `1` | Коефіцієнт масштабування |
+| `adjustX` | number | `0` | Коригування горизонтального положення |
+| `adjustY` | number | `0` | Коригування вертикального положення |
+| `landmarks` | object | (обов'язково) | Орієнтири з Фази 1 |
+| `imageWidth` | number | (обов'язково) | Ширина зображення з Фази 1 |
+| `imageHeight` | number | (обов'язково) | Висота зображення з Фази 1 |
+
+## Стирання об'єктів (Inpainting) {#object-erasing-inpainting}
+
+**Маршрут інструмента:** `erase-object`  
+**Модель:** LaMa через ONNX Runtime
+
+Маска надсилається як **друга частина файлу** (ім'я поля `mask`), а не як base64. Білі пікселі в масці позначають області для стирання. Налаштування `format` та `quality` надсилаються як поля форми верхнього рівня.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `file` | file | (обов'язково) | Вихідне зображення (multipart) |
+| `mask` | file | (обов'язково) | Зображення маски (multipart, ім'я поля `mask`, біле = стерти) |
+| `format` | string | `"auto"` | Формат виводу: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Якість виводу |
+
+Прискорюється CUDA за наявності NVIDIA GPU.
+
+## Розширення полотна ШІ {#ai-canvas-expand}
+
+**Маршрут інструмента:** `ai-canvas-expand`  
+**Модель:** outpainting на базі LaMa
+
+Розширює полотно зображення в будь-якому напрямку та заповнює нові області згенерованим ШІ вмістом, що відповідає наявному зображенню.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | Пікселі для розширення зверху |
+| `extendRight` | integer | `0` | Пікселі для розширення справа |
+| `extendBottom` | integer | `0` | Пікселі для розширення знизу |
+| `extendLeft` | integer | `0` | Пікселі для розширення зліва |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Рівень якості |
+| `format` | string | `"auto"` | Формат виводу: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Якість виводу |
+
+Принаймні один напрямок розширення має бути більшим за 0.
+
+## Розумний кроп {#smart-crop}
+
+**Маршрут інструмента:** `smart-crop`  
+**Модель:** розпізнавання облич MediaPipe (лише режим облич)
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | Стратегія кропу: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Стратегія для режиму об'єкта |
+| `width` | integer | - | Ширина виводу |
+| `height` | integer | - | Висота виводу |
+| `padding` | integer (0-50) | `0` | Відсоток відступу навколо об'єкта |
+| `facePreset` | string | `"head-shoulders"` | Попередньо задане кадрування, коли `mode=face` |
+| `sensitivity` | number (0-1) | `0.5` | Поріг розпізнавання облич |
+| `threshold` | integer (0-255) | `30` | Поріг розпізнавання фону (режим обрізання) |
+| `padToSquare` | boolean | `false` | Доповнити обрізаний результат до квадрата |
+| `padColor` | string | `"#ffffff"` | Колір фону для квадратного доповнення |
+| `targetSize` | integer | - | Цільовий розмір для доповненого виводу (пікселі) |
+| `quality` | integer (1-100) | - | Якість виводу |
+
+Застарілі значення `mode` `attention` та `content` приймаються та зіставляються з `subject` і `trim` відповідно.
+
+**Попередньо задані параметри облич:**
+
+| Пресет | Найкраще для |
+|--------|---------|
+| `closeup` | Портретні знімки |
+| `head-shoulders` | Фото профілю |
+| `upper-body` | LinkedIn / офіційні |
+| `half-body` | Уся верхня частина тіла |
+
+## Транскрибування аудіо {#transcribe-audio}
+
+**Маршрут інструмента:** `transcribe-audio`  
+**Модель:** faster-whisper
+
+Перетворює мовлення на текст. Підтримує формати виводу: звичайний текст, SRT та VTT.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Формат виводу |
+
+## Автосубтитри {#auto-subtitles}
+
+**Маршрут інструмента:** `auto-subtitles`  
+**Модель:** faster-whisper (витягає аудіо з відео, потім транскрибує)
+
+Генерує файли субтитрів з аудіодоріжки відео.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | Формат вихідних субтитрів |
+
+## Виправлення прозорості PNG {#png-transparency-fixer}
+
+**Маршрут інструмента:** `transparency-fixer`  
+**Модель:** матування HR BiRefNet (роздільна здатність 2048x2048)
+
+Виправляє «псевдопрозорі» PNG, де фон було видалено, але залишилися облямівка, ореоли чи напівпрозорі артефакти. Використовує модель матування високої роздільної здатності BiRefNet для створення чистого альфа-каналу, а потім застосовує налаштовувану обробку прибирання облямівки, щоб усунути колірне забруднення вздовж країв.
+
+**Ланцюг резервів OOM:** Якщо матування HR BiRefNet перевищує доступну пам'ять, інструмент автоматично переходить на `birefnet-general`, а потім на `u2net`.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | Сила прибирання облямівки країв для усунення колірного забруднення |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Формат вихідного зображення |
+| `removeWatermark` | boolean | `false` | Застосувати попередню обробку видалення водяного знака (медіанний фільтр) |
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@fake-transparent.png" \
+  -F 'settings={"defringe":30,"outputFormat":"png"}'
+```
+
+---
+
+## Інструменти з необов'язковими можливостями ШІ {#tools-with-optional-ai-capabilities}
+
+Наведені нижче інструменти не є інструментами допоміжного процесу Python, але використовують функції ШІ, коли ввімкнено певні опції.
+
+### Покращення зображення {#image-enhancement}
+
+**Маршрут інструмента:** `image-enhancement`  
+**Рушій:** на основі аналізу (гістограма та статистика Sharp)
+
+Аналізує зображення та застосовує автоматичні корекції експозиції, контрасту, балансу білого, насиченості, різкості та шуму. Підтримує режими для конкретних сцен.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Режим сцени для налаштування корекцій |
+| `intensity` | number (0-100) | `50` | Загальна сила корекції |
+| `corrections.exposure` | boolean | `true` | Застосувати корекцію експозиції |
+| `corrections.contrast` | boolean | `true` | Застосувати корекцію контрасту |
+| `corrections.whiteBalance` | boolean | `true` | Застосувати корекцію балансу білого |
+| `corrections.saturation` | boolean | `true` | Застосувати корекцію насиченості |
+| `corrections.sharpness` | boolean | `true` | Застосувати корекцію різкості |
+| `corrections.denoise` | boolean | `true` | Застосувати шумозаглушення |
+| `deepEnhance` | boolean | `false` | Увімкнути видалення шуму ШІ через SCUNet (потребує набору `upscale-enhance`) |
+
+Додатковий кінцевий пункт аналізу доступний за `POST /api/v1/tools/image/image-enhancement/analyze`, який повертає виявлені корекції без їх застосування.
+
+### Зміна розміру з урахуванням вмісту (Seam Carving) {#content-aware-resize-seam-carving}
+
+**Маршрут інструмента:** `content-aware-resize`  
+**Рушій:** бінарник Go `caire` (не Python: без вигоди від GPU)
+
+Розумно змінює розмір зображень, видаляючи низькоенергетичні шви та зберігаючи важливий вміст.
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `width` | number | - | Цільова ширина |
+| `height` | number | - | Цільова висота |
+| `protectFaces` | boolean | `false` | Захистити розпізнані області облич (потребує набору `face-detection`) |
+| `blurRadius` | number (0-20) | `4` | Попереднє розмиття для обчислення енергії |
+| `sobelThreshold` | number (1-20) | `2` | Поріг чутливості країв |
+| `square` | boolean | `false` | Примусовий квадратний вивід |
@@ -0,0 +1,211 @@
+---
+description: "Довідник операцій рушія зображень. Усі операції обробки зображень на основі Sharp та їхні параметри."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 9aa73cb2e6da
+---
+
+# Рушій зображень {#image-engine}
+
+Пакет `@snapotter/image-engine` обробляє всі операції із зображеннями, що не належать до AI. Він обгортає [Sharp](https://sharp.pixelplumbing.com/) і виконується повністю в межах процесу без зовнішніх залежностей.
+
+## Операції {#operations}
+
+### resize {#resize}
+
+Масштабувати зображення до конкретних розмірів або за відсотком.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `width` | number | Цільова ширина в пікселях |
+| `height` | number | Цільова висота в пікселях |
+| `fit` | string | `cover`, `contain`, `fill`, `inside` або `outside` |
+| `withoutEnlargement` | boolean | Якщо true, не збільшуватиме менші зображення |
+| `percentage` | number | Масштабувати за відсотком замість абсолютних розмірів |
+
+Можна задати `width`, `height` або обидва. Якщо задати лише один, інший обчислюється для збереження співвідношення сторін.
+
+### crop {#crop}
+
+Вирізати прямокутну область із зображення.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `left` | number | Зсув X від лівого краю |
+| `top` | number | Зсув Y від верхнього краю |
+| `width` | number | Ширина області обрізання |
+| `height` | number | Висота області обрізання |
+| `unit` | string | `px` (за замовчуванням) або `percent` |
+
+### rotate {#rotate}
+
+Повернути зображення на заданий кут.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `angle` | number | Кут повороту в градусах (0-360) |
+| `background` | string | Колір заливки відкритої області (за замовчуванням: `#000000`). Застосовується лише до кутів, відмінних від 90 градусів. |
+
+### flip {#flip}
+
+Віддзеркалити зображення горизонтально, вертикально або обидва способи. Принаймні один має бути true.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `horizontal` | boolean | Віддзеркалити зліва направо |
+| `vertical` | boolean | Віддзеркалити зверху вниз |
+
+### convert {#convert}
+
+Змінити формат зображення.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `format` | string | Цільовий формат: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | Якість стиснення (1-100, застосовується до форматів зі втратами) |
+
+Перші сім форматів (від `jpg` до `jxl`) кодуються Sharp у межах процесу. Решта форматів використовують зовнішні кодери на рівні API: `heic`/`heif` через heif-enc, `bmp`/`ico` через ImageMagick, `jp2` через opj_compress, а `qoi` через вбудований кодек TypeScript.
+
+### compress {#compress}
+
+Зменшити розмір файлу, зберігаючи той самий формат.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `quality` | number | Цільова якість (1-100) |
+| `targetSizeBytes` | number | Опціональний цільовий розмір файлу в байтах |
+| `format` | string | Опціональне перевизначення формату |
+
+### strip-metadata {#strip-metadata}
+
+Видалити метадані EXIF, IPTC, XMP та ICC із зображення. Без параметрів (або з `stripAll: true`) видаляє все. Передайте окремі прапорці для вибіркового видалення.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `stripAll` | boolean | Видалити всі метадані (за замовчуванням, коли прапорці не задано) |
+| `stripExif` | boolean | Видалити дані EXIF (включно з GPS, якщо `stripGps` не задано окремо) |
+| `stripGps` | boolean | Видалити дані GPS-локації |
+| `stripIcc` | boolean | Видалити колірний профіль ICC |
+| `stripXmp` | boolean | Видалити метадані XMP |
+
+### Корекції кольору {#color-adjustments}
+
+Ці операції змінюють властивості кольору зображення. Кожна приймає одне числове значення.
+
+| Операція | Параметр | Діапазон | Опис |
+|---|---|---|---|
+| `brightness` | `value` | -100 до 100 | Налаштувати яскравість |
+| `contrast` | `value` | -100 до 100 | Налаштувати контраст |
+| `saturation` | `value` | -100 до 100 | Налаштувати насиченість кольору |
+
+### Колірні фільтри {#color-filters}
+
+Ці застосовують фіксоване перетворення кольору. Вони не приймають параметрів.
+
+| Операція | Опис |
+|---|---|
+| `grayscale` | Перетворити на відтінки сірого |
+| `sepia` | Застосувати тон сепії |
+| `invert` | Інвертувати всі кольори |
+
+### Колірні канали {#color-channels}
+
+Налаштувати окремі колірні канали RGB. Значення є множниками, де 100 = без змін.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `red` | number | Множник червоного каналу (0 до 200, 100 = без змін) |
+| `green` | number | Множник зеленого каналу (0 до 200, 100 = без змін) |
+| `blue` | number | Множник синього каналу (0 до 200, 100 = без змін) |
+
+### sharpen {#sharpen}
+
+Просте підвищення різкості, кероване одним значенням.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `value` | number | Інтенсивність підвищення різкості (0 до 100). Зіставляється з сигмою Гауса 0.5-10. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+Розширене підвищення різкості з трьома доступними методами й опціональним попереднім проходом зменшення шуму.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask` або `high-pass` |
+| `sigma` | number | Радіус розмиття за Гаусом, 0.5-10 (адаптивний) |
+| `m1` | number | Підвищення різкості плоских областей, 0-10 (адаптивне) |
+| `m2` | number | Підвищення різкості текстурованих областей, 0-20 (адаптивне) |
+| `x1` | number | Поріг плоского/зубчастого, 0-10 (адаптивний) |
+| `y2` | number | Макс. освітлення (обмеження ореолу), 0-50 (адаптивне) |
+| `y3` | number | Макс. затемнення (обмеження ореолу), 0-50 (адаптивне) |
+| `amount` | number | Відсоток інтенсивності, 0-500 (unsharp-mask) |
+| `radius` | number | Радіус розмиття, 0.1-5.0 (unsharp-mask) |
+| `threshold` | number | Мінімальна яскравість краю, 0-255 (unsharp-mask) |
+| `strength` | number | Сила змішування, 0-100 (high-pass) |
+| `kernelSize` | number | `3` або `5` для ядра 3x3 / 5x5 (high-pass) |
+| `denoise` | string | Попередній прохід зменшення шуму: `off`, `light`, `medium` або `strong` |
+
+Параметри залежать від методу. Надавайте лише ті, що стосуються обраного методу.
+
+### color-blindness {#color-blindness}
+
+Симулювати порушення колірного зору за допомогою матриці рекомбінації кольорів 3x3.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `type` | string | Один із: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+Записати або видалити окремі поля метаданих EXIF/IPTC без видалення всього блоку.
+
+| Параметр | Тип | Опис |
+|---|---|---|
+| `artist` | string | Тег EXIF Artist |
+| `copyright` | string | Тег EXIF Copyright |
+| `imageDescription` | string | Тег EXIF ImageDescription |
+| `software` | string | Тег EXIF Software |
+| `dateTime` | string | Тег EXIF DateTime |
+| `dateTimeOriginal` | string | Тег EXIF DateTimeOriginal |
+| `clearGps` | boolean | Видалити всі теги GPS |
+| `fieldsToRemove` | string[] | Список імен полів EXIF для видалення |
+
+Усі параметри опціональні. Поля, перелічені в `fieldsToRemove`, видаляються з наявного блоку EXIF. Поля, задані через іменовані параметри, записуються (або перезаписуються). Двійкові/небезпечні ключі на кшталт MakerNote мовчки ігноруються.
+
+## Визначення формату {#format-detection}
+
+Рушій визначає вхідні формати автоматично за заголовками файлів, а не лише за розширеннями. Це означає, що файл `.jpg`, який насправді є PNG, буде оброблено правильно. Визначення використовує багаторівневий підхід: спочатку магічні байти, потім розширення файлу як резервний варіант.
+
+SnapOtter підтримує **55+ вхідних форматів** та **13 вихідних форматів**, включно з 23 форматами RAW камер від 20+ брендів, професійними форматами (PSD, EPS, OpenEXR, HDR), сучасними кодеками (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) та науковими/ігровими форматами (FITS, DDS). Декодування виконується Sharp нативно, де це можливо, з автоматичним переходом до ImageMagick, LibRaw та спеціалізованих CLI-декодерів.
+
+Повний перелік дивіться на сторінці [Підтримувані формати](/uk/guide/supported-formats).
+
+## Витягання метаданих {#metadata-extraction}
+
+Інструмент `info` повертає метадані зображення. Повний довідник полів дивіться в [Image Info](/uk/tools/image/info).
+
+```json
+{
+  "filename": "photo.jpg",
+  "fileSize": 2450000,
+  "width": 4032,
+  "height": 3024,
+  "format": "jpeg",
+  "channels": 3,
+  "hasAlpha": false,
+  "colorSpace": "srgb",
+  "density": 72,
+  "isProgressive": false,
+  "hasExif": true,
+  "hasIcc": true,
+  "hasXmp": false,
+  "bitDepth": "8",
+  "pages": 1,
+  "histogram": [
+    { "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
+    { "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
+    { "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
+  ]
+}
+```
@@ -0,0 +1,702 @@
+---
+description: "Повний довідник REST API. Кінцеві точки інструментів, пакетна обробка, конвеєри, бібліотека файлів, автентифікація, команди й адміністративні операції."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: 20d37040e8ea
+---
+
+# Довідник REST API {#rest-api-reference}
+
+Інтерактивна документація API з прикладами запитів і відповідей доступна за адресою [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
+
+Машиночитні специфікації:
+- `/api/v1/openapi.yaml` - специфікація OpenAPI 3.1
+- `/llms.txt` - зручне для LLM резюме
+- `/llms-full.txt` - повна зручна для LLM документація
+
+## Автентифікація {#authentication}
+
+Усі кінцеві точки потребують автентифікації, окрім випадків, коли `AUTH_ENABLED=false`.
+
+### Токен сесії {#session-token}
+
+```bash
+# Login
+curl -X POST http://localhost:1349/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}'
+# Returns: {"token":"<session-token>"}
+
+# Use token
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer <session-token>"
+```
+
+Сесії завершуються через 7 днів (налаштовується через `SESSION_DURATION_HOURS`).
+
+### API-ключі {#api-keys}
+
+```bash
+# Create a key (returns key once - store it)
+curl -X POST http://localhost:1349/api/v1/api-keys \
+  -H "Authorization: Bearer <session-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-script"}'
+# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}
+
+# Use the key
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer si_<your-key>"
+```
+
+Ключі мають префікс `si_` і зберігаються як хеші scrypt: неопрацьований ключ показується один раз і надалі його неможливо отримати.
+
+### Кінцеві точки автентифікації {#auth-endpoints}
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Публічний | Вхід, отримання токена сесії |
+| `POST` | `/api/auth/logout` | Автентиф. | Знищення поточної сесії |
+| `GET` | `/api/auth/session` | Автентиф. | Перевірка поточної сесії |
+| `POST` | `/api/auth/change-password` | Автентиф. | Зміна власного пароля (робить недійсними всі інші сесії + API-ключі) |
+| `GET` | `/api/auth/users` | Адмін | Список усіх користувачів |
+| `POST` | `/api/auth/register` | Адмін | Створення нового користувача |
+| `PUT` | `/api/auth/users/:id` | Адмін | Оновлення ролі або команди користувача |
+| `POST` | `/api/auth/users/:id/reset-password` | Адмін | Скидання пароля користувача |
+| `DELETE` | `/api/auth/users/:id` | Адмін | Видалення користувача |
+| `GET` | `/api/v1/config/auth` | Публічний | Перевірка, чи ввімкнено автентифікацію (`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | Автентиф. | Початок реєстрації TOTP MFA. Потребує корпоративної можливості `mfa` |
+| `POST` | `/api/auth/mfa/verify` | Автентиф. | Підтвердження реєстрації MFA кодом TOTP |
+| `POST` | `/api/auth/mfa/complete` | Публічний | Завершення очікуваного виклику входу MFA |
+| `POST` | `/api/auth/mfa/disable` | Автентиф. | Вимкнення MFA для поточного користувача |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Адмін (`users:manage`) | Скидання MFA для користувача |
+| `GET` | `/api/auth/oidc/login` | Публічний | Початок входу OIDC, коли OIDC увімкнено |
+| `GET` | `/api/auth/oidc/callback` | Публічний | Зворотний виклик авторизації OIDC |
+| `GET` | `/api/auth/saml/metadata` | Публічний | XML метаданих SAML SP, коли SAML увімкнено |
+| `GET` | `/api/auth/saml/login` | Публічний | Початок входу SAML |
+| `POST` | `/api/auth/saml/callback` | Публічний | Служба споживача твердження SAML |
+
+Коли для користувача ввімкнено MFA, `POST /api/auth/login` повертає `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` замість токена сесії. Надішліть цей `mfaToken` разом із кодом TOTP або кодом відновлення на `/api/auth/mfa/complete`.
+
+### Дозволи {#permissions}
+
+| Дозвіл | Адмін | Користувач |
+|-----------|:-----:|:----:|
+| Використання інструментів | ✓ | ✓ |
+| Власні файли/конвеєри/API-ключі | ✓ | ✓ |
+| Перегляд файлів/конвеєрів/ключів усіх користувачів | ✓ | - |
+| Запис налаштувань | ✓ | - |
+| Керування користувачами і командами | ✓ | - |
+| Керування брендингом | ✓ | - |
+
+## Перевірка стану {#health-check}
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Публічний | Базова перевірка стану. Повертає `{"status":"healthy","version":"..."}` зі статусом 200 або `{"status":"unhealthy"}` зі статусом 503, якщо база даних недоступна. |
+| `GET` | `/api/v1/readyz` | Публічний | Зонд готовності. Перевіряє PostgreSQL, Redis, дисковий простір і S3, якщо його налаштовано. Повертає 503, коли екземпляр не повинен приймати трафік. |
+| `GET` | `/api/v1/admin/health` | Адмін (`system:health`) | Детальна діагностика, зокрема час безперервної роботи, режим сховища, стан бази даних, стан черги і доступність GPU. |
+
+## Використання інструментів {#using-tools}
+
+Кожен інструмент дотримується однакового шаблону:
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'settings={"width":800,"height":600}'
+
+# Batch (returns ZIP)
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'settings={...}'
+```
+
+`<section>` є одним з `image`, `video`, `audio`, `pdf` або `files`.
+
+- Завантаження здійснюється через `multipart/form-data`.
+- `settings` є JSON-рядком з опціями, специфічними для інструмента.
+- `clientJobId` є необов'язковим полем форми для наданого викликачем співвіднесення прогресу.
+- `fileId` є необов'язковим полем форми, що посилається на наявний елемент бібліотеки файлів. Коли воно присутнє, оброблений результат зберігається як нова версія, а відповідь містить `savedFileId`.
+- **Швидкі інструменти** зазвичай повертають JSON зі статусом 200: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Отримайте оброблений файл з `downloadUrl`.
+- **Будь-який поставлений у чергу інструмент** може повернути JSON зі статусом 202, якщо він тривалий або перевищує вікно синхронного очікування: `{"jobId":"...","async":true}`. Підключіться до SSE для відстеження прогресу, а потім завантажте результат після завершення (див. [Відстеження прогресу](#progress-tracking)).
+- **Пакетні** маршрути повертають ZIP-архів, що передається напряму (із заголовком `X-Job-Id`), для інструментів, зареєстрованих у загальному пакетному реєстрі.
+
+## Довідник інструментів {#tools-reference}
+
+### Пресети конвертації {#conversion-presets}
+
+Спільний каталог містить 83 виділені кінцеві точки пресетів конвертації, як-от `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` і `excel-to-csv`. Пресети є повноцінними маршрутами інструментів:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+Кожен пресет фіксує вихідний формат і делегує базовому інструменту, як-от `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` або `convert-spreadsheet`. Повну таблицю маршрутів і необов'язкові налаштування див. у [Пресети конвертації](/uk/tools/conversion-presets).
+
+### Основне {#essentials}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `resize` | Зміна розміру | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, плюс 23 пресети для соцмереж |
+| `crop` | Обрізання | `left`, `top`, `width`, `height`, `unit` (px/percent) |
+| `rotate` | Обертання і віддзеркалення | `angle`, `horizontal` (bool), `vertical` (bool) |
+| `convert` | Конвертація | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
+| `compress` | Стиснення | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
+
+### Оптимізація {#optimization}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `optimize-for-web` | Оптимізація для вебу | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
+| `strip-metadata` | Видалення метаданих | - |
+| `edit-metadata` | Редагування метаданих | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
+| `bulk-rename` | Масове перейменування | `pattern` (підтримує `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
+| `image-to-pdf` | Зображення в PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
+| `favicon` | Генератор фавіконок | `padding`, `backgroundColor`, `borderRadius` - генерує всі стандартні розміри |
+
+### Коригування {#adjustments}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `adjust-colors` | Коригування кольорів | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
+| `sharpening` | Різкість | `method` (adaptive/unsharp-mask/high-pass), `sigma`, `m1`, `m2`, `x1`, `y2`, `y3`, `amount`, `radius`, `threshold`, `strength`, `kernelSize` (3/5), `denoise` (off/light/medium/strong) |
+| `replace-color` | Заміна кольору | `sourceColor`, `targetColor` (замінник), `makeTransparent`, `tolerance` |
+| `color-blindness` | Симуляція дальтонізму | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, за замовчуванням "deuteranomaly") |
+| `duotone` | Дуотон | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Пікселізація | `blockSize` (2-128), `region` ({left, top, width, height} для часткової пікселізації) |
+| `vignette` | Віньєтка | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### AI-інструменти {#ai-tools}
+
+Усі AI-інструменти працюють на вашому обладнанні: CPU за замовчуванням або NVIDIA CUDA, коли доступний підтримуваний GPU NVIDIA. Прискорення на iGPU Intel/AMD через VA-API, Quick Sync або OpenCL наразі не підтримується для AI-інференсу. Інтернет не потрібен.
+
+| ID інструмента | Назва | AI-модель | Ключові налаштування |
+|---------|------|---------|-------------|
+| `remove-background` | Видалення фону | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | Масштабування зображення | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | Ластик об'єктів | LaMa (ONNX) | Маска надсилається як друга частина файлу (ім'я поля `mask`), `format`, `quality` |
+| `ocr` | OCR / Витяг тексту | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `blur-faces` | Розмиття облич / PII | MediaPipe | `blurRadius`, `sensitivity` |
+| `smart-crop` | Розумне обрізання | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
+| `image-enhancement` | Покращення зображення | На основі аналізу | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
+| `enhance-faces` | Покращення облич | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
+| `colorize` | AI-розфарбовування | DDColor | `intensity`, `model` |
+| `noise-removal` | Видалення шуму | Багаторівневе шумозаглушення | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
+| `red-eye-removal` | Видалення ефекту червоних очей | Орієнтири обличчя + аналіз кольору | `sensitivity`, `strength` |
+| `restore-photo` | Реставрація фото | Багатокроковий конвеєр | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | Фото на паспорт | Орієнтири MediaPipe | Двофазний процес. Аналіз використовує multipart `file`; генерація використовує JSON з `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), орієнтирами, розмірами зображення |
+| `content-aware-resize` | Зміна розміру з урахуванням вмісту | Виріз швів (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
+| `transparency-fixer` | Виправлення прозорості PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
+| `background-replace` | Заміна фону | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
+| `blur-background` | Розмиття фону | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
+| `ai-canvas-expand` | AI-розширення полотна | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### Водяні знаки й накладення {#watermark-overlay}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `watermark-text` | Текстовий водяний знак | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | Водяний знак зображенням | `opacity`, `position`, `scale` - другий файл є водяним знаком |
+| `text-overlay` | Накладення тексту | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | Композиція зображень | `x`, `y`, `opacity`, `blend` - другий файл накладається зверху |
+| `meme-generator` | Генератор мемів | `templateId`, `textLayout` (top-bottom/top-only/bottom-only/center/side-by-side), `textBoxes` ([{id, text}]), `fontFamily` (anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto), `fontSize`, `textColor`, `strokeColor`, `textAlign`, `allCaps`. Підтримує режим шаблону (тіло JSON з `templateId`) або режим власного зображення (multipart з файлом). |
+
+### Утиліти {#utilities}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `info` | Інформація про зображення | - (повертає width, height, format, size, channels, hasAlpha, DPI, EXIF) |
+| `compare` | Порівняння зображень | `mode` (side-by-side/overlay/diff), `diffThreshold` - другий файл є ціллю порівняння |
+| `find-duplicates` | Пошук дублікатів | `threshold` (відстань перцептивного хешу, за замовчуванням 8) - багатофайловий |
+| `color-palette` | Палітра кольорів | `count` (кількість домінантних кольорів), `format` (hex/rgb) |
+| `qr-generate` | Генератор QR-коду | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (необов'язковий файл) |
+| `barcode-read` | Зчитувач штрихкодів | - (автоматично розпізнає QR, EAN, Code128, DataMatrix тощо) |
+| `image-to-base64` | Зображення в Base64 | `format` (data-uri/plain), `mimeType` |
+| `html-to-image` | HTML у зображення | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
+| `histogram` | Гістограма | `scale` (linear/log) - повертає діаграму RGB-гістограми + статистику по кожному каналу |
+| `lqip-placeholder` | LQIP-заповнювач | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
+| `barcode-generate` | Генератор штрихкодів | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Тіло JSON, без завантаження файлу. |
+
+### Компонування й композиція {#layout-composition}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `collage` | Колаж / Сітка | `template` (25+ макетів), `gap`, `backgroundColor`, `borderRadius` - багатофайловий |
+| `stitch` | Зшивання / Об'єднання | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - багатофайловий |
+| `split` | Розділення зображення | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
+| `border` | Рамка й обрамлення | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
+| `beautify` | Прикрашання скріншота | `backgroundType` (solid/linear-gradient/radial-gradient/image/transparent), `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame` (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), `socialPreset` (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), `watermarkText`, `outputFormat` |
+| `circle-crop` | Кругле обрізання | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
+| `image-pad` | Заповнення зображення | `target` (16:9/9:16/1:1/4:3/3:4/custom), `ratioW`, `ratioH`, `background` (color/transparent/blur), `color` (hex), `padding` (0-50%) |
+| `sprite-sheet` | Спрайт-лист | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - багатофайловий (2-64 зображення) |
+
+### Формат і конвертація {#format-conversion}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `svg-to-raster` | SVG у растр | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
+| `vectorize` | Зображення в SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
+| `gif-tools` | GIF-інструменти | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), параметри, специфічні для дії |
+| `gif-webp` | Конвертер GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
+
+### Відеоінструменти {#video-tools}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `convert-video` | Конвертація відео | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
+| `compress-video` | Стиснення відео | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
+| `trim-video` | Обрізання відео | `startS`, `endS`, `precise` (bool, покадрово точний виріз) |
+| `mute-video` | Вимкнення звуку відео | - |
+| `video-to-gif` | Відео в GIF | `fps` (1-30), `width`, `startS`, `durationS` (макс. 60 с) |
+| `resize-video` | Зміна розміру відео | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
+| `crop-video` | Обрізання відео за краями | `width`, `height`, `x`, `y` |
+| `rotate-video` | Обертання відео | `transform` (cw90/ccw90/180/hflip/vflip) |
+| `change-fps` | Зміна FPS | `fps` (1-120) |
+| `video-color` | Колір відео | `brightness`, `contrast`, `saturation`, `gamma` |
+| `video-speed` | Швидкість відео | `factor` (0.25-4), `keepPitch` (bool) |
+| `reverse-video` | Реверс відео | - (макс. 5 хвилин) |
+| `video-loudnorm` | Нормалізація звуку | - (EBU R128) |
+| `aspect-pad` | Заповнення за співвідношенням | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
+| `blur-pad` | Заповнення розмиттям | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
+| `watermark-video` | Водяний знак на відео | `text`, `position`, `fontSize`, `opacity`, `color` |
+| `stabilize-video` | Стабілізація відео | `smoothing` (5-60, у кадрах) |
+| `gif-to-video` | GIF у відео | `format` (mp4/webm/mov) |
+| `video-to-webp` | Відео в WebP | `fps`, `width`, `quality`, `loop` (bool) |
+| `video-to-frames` | Відео в кадри | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
+| `merge-videos` | Об'єднання відео | - (багатофайловий, нормалізовано до роздільної здатності першого відео) |
+| `replace-audio` | Заміна звуку | - (відео + аудіофайл, два файли) |
+| `burn-subtitles` | Вшивання субтитрів | `fontSize` (8-72) - відео + файл субтитрів |
+| `embed-subtitles` | Вбудовування субтитрів | `language` (код ISO 639-2/B) - відео + файл субтитрів |
+| `extract-subtitles` | Витяг субтитрів | - (виводить SRT) |
+| `images-to-video` | Зображення у відео | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - багатофайловий |
+| `video-metadata` | Очищення метаданих відео | - |
+| `auto-subtitles` | Автосубтитри (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
+| `extract-audio` | Витяг звуку | `format` (mp3/wav/m4a/ogg) |
+
+### Аудіоінструменти {#audio-tools}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `convert-audio` | Конвертація аудіо | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
+| `trim-audio` | Обрізання аудіо | `startS`, `endS` |
+| `volume-adjust` | Регулювання гучності | `gainDb` (-30 до 30) |
+| `normalize-audio` | Нормалізація звуку | - (EBU R128, -16 LUFS) |
+| `fade-audio` | Затухання аудіо | `fadeInS` (0-30), `fadeOutS` (0-30) |
+| `reverse-audio` | Реверс аудіо | - |
+| `audio-speed` | Швидкість аудіо | `factor` (0.25-4) |
+| `pitch-shift` | Зсув висоти тону | `semitones` (-12 до 12) |
+| `audio-channels` | Аудіоканали | `mode` (stereo-to-mono/mono-to-stereo/swap) |
+| `silence-removal` | Видалення тиші | `thresholdDb` (-80 до -20), `minSilenceS` (0.1-5) |
+| `noise-reduction` | Зменшення шуму | `strength` (light/medium/strong) |
+| `merge-audio` | Об'єднання аудіо | `format` (mp3/wav/flac/m4a) - багатофайловий |
+| `split-audio` | Розділення аудіо | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
+| `ringtone-maker` | Створення рінгтона | `startS`, `durationS` (1-30) |
+| `waveform-image` | Зображення хвилі | `width`, `height`, `color` (hex) |
+| `audio-metadata` | Метадані аудіо | `strip` (bool), `title`, `artist`, `album` |
+| `transcribe-audio` | Транскрибування аудіо (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
+
+### Інструменти для документів {#document-tools}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `merge-pdf` | Об'єднання PDF | - (багатофайловий, до 20 PDF) |
+| `split-pdf` | Розділення PDF | `mode` (range/every), `range`, `everyN` (1-500) |
+| `compress-pdf` | Стиснення PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
+| `rotate-pdf` | Обертання PDF | `angle` (90/180/270), `range` (діапазон сторінок) |
+| `extract-pages` | Витяг сторінок | `range` (синтаксис qpdf, напр. "1-5,8,10-z") |
+| `remove-pages` | Видалення сторінок | `pages` (діапазон qpdf для видалення) |
+| `organize-pdf` | Упорядкування PDF | `order` (порядок сторінок qpdf, напр. "3,1,2,5-z") |
+| `protect-pdf` | Захист PDF | `userPassword`, `ownerPassword` (AES-256) |
+| `unlock-pdf` | Розблокування PDF | `password` |
+| `repair-pdf` | Відновлення PDF | - |
+| `linearize-pdf` | Веб-оптимізація PDF | - (лінеаризація для швидкого перегляду у вебі) |
+| `grayscale-pdf` | PDF у відтінках сірого | - |
+| `pdfa-convert` | Конвертація в PDF/A | - (архівний PDF/A-2) |
+| `crop-pdf` | Обрізання PDF | `margin` (0-2000 пунктів) |
+| `nup-pdf` | N-up PDF | `perSheet` (2/3/4/8/9/12/16) |
+| `booklet-pdf` | Буклет PDF | `perSheet` (2/4/6/8) |
+| `watermark-pdf` | Водяний знак PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
+| `pdf-page-numbers` | Номери сторінок PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
+| `flatten-pdf` | Зведення PDF | - (запікає форми й анотації) |
+| `redact-pdf` | Редагування PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | Підпис PDF | Власний multipart-маршрут з PDF `file`, файлами підписів `sig0`, `sig1` і JSON-масивом `placements` |
+| `pdf-to-text` | PDF у текст | - |
+| `pdf-to-word` | PDF у Word | - |
+| `pdf-metadata` | Метадані PDF | `title`, `author`, `subject`, `keywords` |
+| `convert-document` | Конвертація документа | `format` (docx/odt/rtf/txt) |
+| `convert-presentation` | Конвертація презентації | `format` (pptx/odp) |
+| `convert-spreadsheet` | Конвертація електронної таблиці | `format` (xlsx/ods/csv) |
+| `excel-to-pdf` | Excel у PDF | - |
+| `word-to-pdf` | Word у PDF | - |
+| `powerpoint-to-pdf` | PowerPoint у PDF | - |
+| `html-to-pdf` | HTML у PDF | - (віддалені ресурси вимкнено) |
+| `markdown-to-docx` | Markdown у Word | - |
+| `markdown-to-html` | Markdown у HTML | - |
+| `markdown-to-pdf` | Markdown у PDF | - (віддалені ресурси вимкнено) |
+| `epub-convert` | Конвертація EPUB | `format` (pdf/docx/html/md) |
+| `to-epub` | Конвертація в EPUB | - (приймає .docx, .md, .html, .txt) |
+| `ocr-pdf` | PDF OCR (AI) | `quality` (fast/balanced/best), `language` (auto/en/de/fr/es/zh/ja/ko), `pages` |
+| `pdf-to-image` | PDF у зображення | `pages` (all/range), `format`, `dpi`, `quality` |
+| `pdf-to-jpg` | PDF у JPG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-png` | PDF у PNG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-tiff` | PDF у TIFF | `pages`, `dpi`, `quality`, `colorMode` |
+
+### Файлові інструменти {#file-tools}
+
+| ID інструмента | Назва | Ключові налаштування |
+|---------|------|-------------|
+| `chart-maker` | Створення діаграм | `kind` (bar/line/pie), `title`, `width`, `height` |
+| `csv-excel` | CSV у Excel | `sheet` (номер аркуша для вхідного XLSX) - двонапрямний |
+| `csv-json` | CSV у JSON | `pretty` (bool) - двонапрямний |
+| `json-xml` | JSON у XML | `pretty` (bool) - двонапрямний |
+| `split-csv` | Розділення CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
+| `merge-csvs` | Об'єднання CSV | - (багатофайловий, збіжні стовпці) |
+| `yaml-json` | YAML / JSON | - (двонапрямний) |
+| `xml-to-csv` | XML у CSV | - (автоматично знаходить повторювані елементи) |
+| `excel-to-csv` | Excel у CSV | виділений пресет конвертації на основі `convert-spreadsheet` |
+| `create-zip` | Створення ZIP | - (багатофайловий, 2-50 файлів) |
+| `extract-zip` | Витяг ZIP | - (захищено від zip-бомб) |
+
+### HTML у зображення {#html-to-image}
+
+Захоплення вебсторінки як зображення. На відміну від інших інструментів, ця кінцева точка приймає `application/json` замість multipart-даних форми (завантаження файлу не потрібне).
+
+**Кінцева точка:** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type:** `application/json`
+
+| Параметр | Тип | За замовчуванням | Опис |
+|-----------|------|---------|-------------|
+| `url` | string | (обов'язковий) | URL для захоплення (лише http/https) |
+| `format` | string | `"png"` | Вихідний формат: `jpg`, `png`, `webp` |
+| `quality` | number | `90` | Якість 1-100 (лише JPG/WebP) |
+| `fullPage` | boolean | `false` | Захоплення всієї прокручуваної сторінки |
+| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
+| `viewportWidth` | number | `1280` | Власна ширина вікна перегляду 320-3840 |
+| `viewportHeight` | number | `720` | Власна висота вікна перегляду 320-2160 |
+
+**Приклад:**
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
+```
+
+**Відповідь:**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### Підмаршрути інструментів {#tool-sub-routes}
+
+Деякі інструменти надають додаткові кінцеві точки понад стандартний `POST /api/v1/tools/<section>/<toolId>`:
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | Повертає ID популярних інструментів, повертаючись до кураторського списку за замовчуванням, коли даних про використання мало |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | Застосовує ефекти фону (color/gradient/blur/shadow) без повторного запуску AI. Використовує кешовану маску з початкового видалення. |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Читає наявні метадані EXIF/IPTC/XMP із зображення |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Перевіряє поля метаданих перед видаленням |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Фаза 1: AI-виявлення облич + видалення фону. Повертає орієнтири обличчя і кешовані дані. |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | Фаза 2: Обрізання, зміна розміру і тайлинг з використанням кешованого аналізу. Без повторного запуску AI. |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | Отримати метадані GIF (кількість кадрів, розміри, тривалість) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Отримати метадані PDF (кількість сторінок, розміри) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Згенерувати попередній перегляд конкретної сторінки PDF |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Отримати метадані PDF для виділеного пресета JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Згенерувати попередній перегляд сторінки PDF для пресета JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Отримати метадані PDF для виділеного пресета PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Згенерувати попередній перегляд сторінки PDF для пресета PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Отримати метадані PDF для виділеного пресета TIFF |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Згенерувати попередній перегляд сторінки PDF для пресета TIFF |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Пакетна конвертація кількох SVG у растр |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Проаналізувати якість зображення і повернути рекомендації щодо покращення |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Легкий попередній перегляд для живого налаштування параметрів. Повертає оптимізоване зображення із заголовками розміру. |
+
+## Пакетна обробка {#batch-processing}
+
+Застосуйте загальний пакетний інструмент до кількох файлів одночасно. Повертає ZIP-архів. Власні багатофайлові або багатокрокові маршрути, як-от підпис PDF, PDF OCR і маршрути пресетів PDF-у-зображення, використовують власний контракт кінцевої точки замість загального маршруту `/batch`.
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F "files=@c.jpg" \
+  -F 'settings={"quality":80}'
+```
+
+Паралелізм контролюється `CONCURRENT_JOBS` (за замовчуванням: автоматично визначається за ядрами CPU). `MAX_BATCH_SIZE` обмежує кількість файлів на пакет (за замовчуванням: 100; встановіть 0 для необмеженої кількості).
+
+## Конвеєри {#pipelines}
+
+### Виконання конвеєра {#execute-a-pipeline}
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/pipeline/execute \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'pipeline={"steps":[
+    {"toolId":"resize","settings":{"width":1200}},
+    {"toolId":"compress","settings":{"quality":80}},
+    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
+  ]}'
+
+# Batch (multiple files → ZIP)
+curl -X POST http://localhost:1349/api/v1/pipeline/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
+```
+
+Вихід кожного кроку є входом наступного кроку. Конвеєри дозволяють 20 кроків за замовчуванням, налаштовується через `MAX_PIPELINE_STEPS`. Встановіть `MAX_PIPELINE_STEPS=0`, щоб зняти обмеження.
+
+### Збереження конвеєрів і керування ними {#save-and-manage-pipelines}
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | Зберегти іменований конвеєр (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | Список збережених конвеєрів (адміни бачать усі; користувачі бачать власні) |
+| `DELETE` | `/api/v1/pipeline/:id` | Видалити (власник або адмін) |
+| `GET` | `/api/v1/pipeline/tools` | Список ID інструментів, дійсних для кроків конвеєра |
+
+## Відстеження прогресу {#progress-tracking}
+
+Тривалі завдання, поставлені в чергу інструменти, пакетні завдання і конвеєри видають прогрес у реальному часі через Server-Sent Events. Потік прогресу є публічним і прив'язується за ID завдання, тож клієнтам не потрібно надсилати заголовок Authorization для його читання.
+
+```bash
+# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
+curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
+```
+
+Формат події:
+```
+data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
+data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
+data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
+```
+
+Ви можете запросити скасування поставленого в чергу або запущеного завдання за допомогою `POST /api/v1/jobs/:jobId/cancel`. Відповідь: `{"canceled":true|false}`.
+
+## Бібліотека файлів {#file-library}
+
+Постійне сховище файлів з історією версій.
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | Завантажити файли в робочу область (тимчасова обробка) |
+| `POST` | `/api/v1/files/upload` | Завантажити файли в постійну бібліотеку файлів |
+| `POST` | `/api/v1/files/save-result` | Зберегти результат обробки інструментом як нову версію файлу |
+| `GET` | `/api/v1/files` | Список збережених файлів (з розбивкою на сторінки, з пошуком) |
+| `GET` | `/api/v1/files/:id` | Отримати метадані файлу + ланцюжок версій |
+| `GET` | `/api/v1/files/:id/download` | Завантажити файл |
+| `GET` | `/api/v1/files/:id/thumbnail` | Отримати мініатюру JPEG 300px |
+| `DELETE` | `/api/v1/files` | Масове видалення файлів та їхніх ланцюжків версій (тіло: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | Отримати віддалені URL у робочу область для імпорту на основі URL |
+| `POST` | `/api/v1/preview` | Згенерувати сумісний з браузером попередній перегляд WebP (для форматів HEIC/HEIF/RAW) |
+| `GET` | `/api/v1/files/:id/preview` | Передати кешований або згенерований сумісний з браузером попередній перегляд для збереженого PDF, офісного документа, відео чи аудіофайлу |
+| `POST` | `/api/v1/preview/generate` | Згенерувати попередній перегляд MP4 або MP3 на вимогу для завантаженого медіафайлу без попереднього збереження |
+| `GET` | `/api/v1/download/:jobId/:filename` | Завантажити оброблений файл з робочої області |
+
+Щоб автоматично зберегти результат інструмента в бібліотеку, включіть `fileId` як поле multipart-форми, що посилається на наявний файл бібліотеки. Оброблений результат буде збережено як нову версію.
+
+## Керування API-ключами {#api-key-management}
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Автентиф. | Згенерувати новий ключ - показується один раз |
+| `GET` | `/api/v1/api-keys` | Автентиф. | Список ключів (name, id, lastUsedAt - не неопрацьований ключ) |
+| `DELETE` | `/api/v1/api-keys/:id` | Автентиф. | Видалити ключ |
+
+## Команди {#teams}
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Адмін (`teams:manage`) | Список команд |
+| `POST` | `/api/v1/teams` | Адмін (`teams:manage`) | Створити команду |
+| `PUT` | `/api/v1/teams/:id` | Адмін (`teams:manage`) | Перейменувати команду |
+| `DELETE` | `/api/v1/teams/:id` | Адмін (`teams:manage`) | Видалити команду (не можна видалити команду за замовчуванням або команди з учасниками) |
+
+## Налаштування {#settings}
+
+Конфігурація ключ-значення в реальному часі (читає будь-який автентифікований користувач, записує лише адмін).
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | Отримати всі налаштування |
+| `PUT` | `/api/v1/settings` | Масове оновлення налаштувань (тіло JSON з парами ключ-значення) |
+| `GET` | `/api/v1/settings/:key` | Отримати конкретне налаштування за ключем |
+
+Відомі ключі: `disabledTools` (JSON-масив ID інструментів), `enableExperimentalTools` (bool-рядок), `loginAttemptLimit` (число).
+
+## Уподобання {#preferences}
+
+Уподобання окремих користувачів відокремлені від налаштувань екземпляра. Будь-який автентифікований користувач може читати й оновлювати власну карту уподобань.
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | Отримати уподобання поточного користувача як `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | Вставити або оновити один чи кілька ключів уподобань для поточного користувача |
+
+## Ролі {#roles}
+
+Керування власними ролями з детальними дозволами.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Адмін (`audit:read`) | Список усіх ролей з кількістю користувачів |
+| `POST` | `/api/v1/roles` | Адмін (`security:manage`) | Створити власну роль (`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | Адмін (`security:manage`) | Оновити власну роль (не можна змінювати вбудовані ролі) |
+| `DELETE` | `/api/v1/roles/:id` | Адмін (`security:manage`) | Видалити власну роль (не можна видаляти вбудовані ролі; постраждалі користувачі повертаються до ролі `user`) |
+
+Доступні дозволи (17): `tools:use`, `files:own`, `files:all`, `apikeys:own`, `apikeys:all`, `pipelines:own`, `pipelines:all`, `settings:read`, `settings:write`, `users:manage`, `teams:manage`, `features:manage`, `system:health`, `audit:read`, `compliance:manage`, `webhooks:manage`, `security:manage`.
+
+## Журнал аудиту {#audit-log}
+
+Кінцева точка лише для адміністраторів для перегляду дій, пов'язаних із безпекою.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Адмін (`audit:read`) | Журнал аудиту з розбивкою на сторінки з необов'язковими фільтрами |
+
+Параметри запиту:
+
+| Параметр | Опис |
+|-----------|-------------|
+| `page` | Номер сторінки (за замовчуванням: 1) |
+| `limit` | Записів на сторінку (за замовчуванням: 50, макс.: 100) |
+| `action` | Фільтр за типом дії (напр. `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | Фільтр за IP-адресою джерела |
+| `from` | Фільтр записів після цієї дати ISO 8601 |
+| `to` | Фільтр записів до цієї дати ISO 8601 |
+
+## Аналітика {#analytics}
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Публічний | Отримати фактичну конфігурацію аналітики (ключ PostHog, Sentry DSN, частота вибірки). Ключі, DSN і ID екземпляра порожні, коли аналітику вимкнено, або через запікання під час компіляції, або через налаштування екземпляра `analyticsEnabled`. |
+| `POST` | `/api/v1/feedback` | Автентиф. | Надіслати явний відгук користувача до налаштованого проєкту PostHog як `feedback_submitted`. Маршрут дотримується шлюзу аналітики, обмежує швидкість подань, видаляє контактні поля, якщо `contactOk` не є true, і ніколи не приймає вмісту файлів, імен файлів, шляхів завантаження чи неопрацьованого приватного тексту помилок. Коли аналітику вимкнено, повертає `{ "ok": true, "accepted": false }`. |
+| `PUT` | `/api/v1/settings` | Адмін (`settings:write`) | Встановити відмову на рівні всього екземпляра. Надішліть тіло JSON `{ "analyticsEnabled": "false" }`, щоб вимкнути аналітику для всіх, або `"true"`, щоб знову її ввімкнути. |
+
+## Можливості / AI-набори {#features-ai-bundles}
+
+Керування наборами AI-можливостей (встановлення/видалення пакетів AI-моделей у середовищі Docker). Віддавайте перевагу кінцевій точці встановлення на рівні інструмента, коли вмикаєте інструмент з власної автоматизації: деякі AI-інструменти потребують більш ніж одного спільного набору, а ця кінцева точка пропускає вже встановлені набори, ставлячи в чергу лише відсутні.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Автентиф. | Список усіх наборів можливостей та їхнього статусу встановлення |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Адмін (`features:manage`) | Встановити набір можливостей (асинхронно, повертає `jobId` для відстеження прогресу) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Адмін (`features:manage`) | Встановити кожен набір, потрібний інструменту; повертає статус queued/skipped для кожного набору |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Адмін (`features:manage`) | Видалити набір можливостей і очистити файли моделей |
+| `GET` | `/api/v1/admin/features/disk-usage` | Адмін (`features:manage`) | Отримати загальне використання диска AI-моделями |
+| `POST` | `/api/v1/admin/features/import` | Адмін (`features:manage`) | Імпортувати офлайн-архів AI-набору |
+
+## Адміністративні операції {#admin-operations}
+
+Операційні кінцеві точки для спостережуваності, підтримки, звітності про використання і стану резервного копіювання.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Адмін (`settings:write`) | Прочитати поточний рівень журналювання середовища виконання |
+| `POST` | `/api/v1/admin/log-level` | Адмін (`settings:write`) | Змінити рівень журналювання середовища виконання (`fatal`, `error`, `warn`, `info`, `debug`, `trace` або `silent`) |
+| `GET` | `/api/v1/metrics` | Адмін (`system:health`) | Метрики Prometheus у текстовому форматі |
+| `GET` | `/api/v1/admin/support-bundle` | Адмін (`system:health`) | Завантажити відредагований діагностичний ZIP-набір підтримки |
+| `GET` | `/api/v1/admin/usage` | Адмін (`audit:read`) | Дані панелі використання, з необов'язковим параметром запиту `days` |
+| `GET` | `/api/v1/admin/backup-status` | Адмін (`system:health`) | Прочитати метадані останнього резервного копіювання і статус свіжості |
+| `POST` | `/api/v1/admin/backup-status` | Адмін (`system:health`) | Записати завершене резервне копіювання (`type`, необов'язково `sizeBytes`, необов'язково `notes`) |
+
+## Корпоративні API {#enterprise-apis}
+
+Ці маршрути ліцензійно обмежені пов'язаною корпоративною можливістю. Вони все одно потребують зазначеного дозволу SnapOtter.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Адмін (`audit:read`) | Експортувати записи аудиту як JSON або CSV з фільтрами |
+| `GET` | `/api/v1/enterprise/config/export` | Адмін (`system:health`) | Експортувати відредаговану конфігурацію екземпляра, власні ролі й команди |
+| `POST` | `/api/v1/enterprise/config/import` | Адмін (`system:health`) | Імпортувати конфігурацію, з необов'язковим пробним запуском |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Адмін (`security:manage`) | Прочитати налаштований білий список CIDR |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Адмін (`security:manage`) | Оновити білий список CIDR із запобіганням самоблокуванню |
+| `GET` | `/api/v1/enterprise/legal-hold` | Адмін (`compliance:manage`) | Список правових утримань користувачів і команд |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Адмін (`compliance:manage`) | Застосувати або зняти правове утримання для користувача чи команди |
+| `POST` | `/api/v1/enterprise/scim/token` | Адмін (`users:manage`) | Згенерувати bearer-токен SCIM, повертається один раз |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Адмін (`users:manage`) | Відкликати поточний bearer-токен SCIM |
+| `GET` | `/api/v1/enterprise/siem/config` | Адмін (`webhooks:manage`) | Прочитати конфігурацію пересилання SIEM |
+| `PUT` | `/api/v1/enterprise/siem/config` | Адмін (`webhooks:manage`) | Оновити конфігурацію пересилання SIEM |
+| `GET` | `/api/v1/enterprise/webhooks` | Адмін (`webhooks:manage`) | Список призначень вебхуків |
+| `POST` | `/api/v1/enterprise/webhooks` | Адмін (`webhooks:manage`) | Створити призначення вебхука |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Адмін (`webhooks:manage`) | Оновити призначення вебхука |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Адмін (`webhooks:manage`) | Видалити призначення вебхука |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Адмін (`webhooks:manage`) | Надіслати тестове корисне навантаження вебхука |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Адмін (`compliance:manage`) | Запустити завдання експорту користувача GDPR |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Адмін (`compliance:manage`) | Прочитати статус експорту GDPR і URL завантаження |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Адмін (`compliance:manage`) | Остаточно очистити дані користувача після підтвердження |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Адмін (`compliance:manage`) | Остаточно очистити дані команди після підтвердження |
+| `GET` | `/api/v1/admin/version` | Адмін (`system:health`) | Прочитати метадані версії застосунку, збірки, Node і схеми |
+| `GET` | `/api/v1/admin/migrations/pending` | Адмін (`system:health`) | Порівняти упаковані міграції із застосованими міграціями |
+| `GET` | `/api/v1/admin/upgrade-check` | Адмін (`system:health`) | Запустити перевірки готовності до оновлення |
+
+### SCIM 2.0 {#scim-2-0}
+
+Кінцеві точки виявлення SCIM є публічними. Кінцеві точки користувачів і груп потребують bearer-токена SCIM, згенерованого вище.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Публічний | Можливості сервера SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | Публічний | Виявлення схеми SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Публічний | Виявлення типів ресурсів SCIM |
+| `GET` | `/api/v1/scim/v2/Users` | Токен SCIM | Список користувачів, з необов'язковим фільтром SCIM |
+| `POST` | `/api/v1/scim/v2/Users` | Токен SCIM | Створити користувача |
+| `GET` | `/api/v1/scim/v2/Users/:id` | Токен SCIM | Отримати користувача |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | Токен SCIM | Замінити користувача |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | Токен SCIM | М'яко деактивувати користувача |
+| `GET` | `/api/v1/scim/v2/Groups` | Токен SCIM | Список команд як груп SCIM |
+| `POST` | `/api/v1/scim/v2/Groups` | Токен SCIM | Створити команду |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | Токен SCIM | Отримати команду |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | Токен SCIM | Замінити команду і членство в групі |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Токен SCIM | Видалити команду |
+
+## Шаблони мемів {#meme-templates}
+
+Допоміжний API для інструмента генерації мемів.
+
+| Метод | Шлях | Доступ | Опис |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Автентиф. | Список усіх доступних шаблонів мемів із позиціями текстових полів |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Автентиф. | Надати повнорозмірне зображення шаблону |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Автентиф. | Надати мініатюру шаблону |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Автентиф. | Надати файл шрифту, що використовується для рендерингу тексту мемів |
+
+## Відповіді з помилками {#error-responses}
+
+Усі помилки повертають JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| Статус | Значення |
+|--------|---------|
+| 400 | Недійсний запит / помилка валідації |
+| 401 | Не автентифіковано |
+| 403 | Недостатньо дозволів |
+| 404 | Ресурс не знайдено |
+| 413 | Файл завеликий (див. `MAX_UPLOAD_SIZE_MB`) |
+| 422 | Обробка не вдалася після валідації |
+| 429 | Обмежено за швидкістю (див. `RATE_LIMIT_PER_MIN`) |
+| 501 | Потрібний AI-набір можливостей не встановлено (`FEATURE_NOT_INSTALLED`) |
+| 500 | Внутрішня помилка сервера |