SnapOtter/apps/docs/ru/api/ai.md

---
description: "Справочник по AI-движку со всеми локальными ML-инструментами. Удаление фона, апскейлинг, OCR, распознавание лиц, реставрация фотографий и другое."
i18n_output_hash: 964be813bc52
i18n_source_hash: aa9a56cdddc7
i18n_provenance: human
---

# Справочник по AI-движку {#ai-engine-reference}

Пакет `@snapotter/ai` координирует собственные инструменты и среду выполнения Python для локальных операций ML. Большинство инструментов ML используют постоянный Python sidecar для быстрого горячего запуска. OCR намеренно отделен: `fast` вызывает собственный двоичный файл Tesseract, в то время как `balanced` и `best` используют выделенный постоянный JSONL dispatcher, прикрепленный к активному неизменяемому поколению RapidOCR под `/data/ai/v3`. Каждый запрос содержит generation lease. Во время обновления SnapOtter запускает smoke test на кандидате перед активацией, атомарно переключается на новый dispatcher, а затем сливает старое поколение перед garbage collection.

NVIDIA CUDA автоматически обнаруживается и используется средами выполнения, которые его поддерживают. OCR использует CPU на каждом хосте, включая системы с графическими процессорами NVIDIA, избегая CUDA и связи драйверов для этого инструмента.

Ускорение через iGPU Intel/AMD посредством VA-API, Quick Sync или OpenCL сегодня не поддерживается для AI-инференса. Проброс `/dev/dri` в контейнер не ускоряет эти инструменты Python-сайдкара, если не доступна NVIDIA GPU с поддержкой CUDA.

19 AI-инструментов Python-сайдкара в четырёх модальностях (изображение, аудио, видео, документ) плюс 2 инструмента с опциональными AI-возможностями. Все модели работают локально: после первоначальной загрузки моделей интернет не требуется.


<!-- korean-ocr-contract:start -->
::: info Совместимость OCR для корейского языка
Быстрый OCR поддерживает `auto`, `en`, `de`, `es`, `fr`, `zh` и `ja`, но не корейский язык (`ko`). Для корейского требуется пакет точного OCR и уровень `balanced` или `best`. Пакет работает в официальных контейнерах Linux amd64 и arm64, включая узлы NVIDIA, где OCR по-прежнему выполняется на CPU. На неподдерживаемой системе возвращается явная ошибка совместимости без скрытого перехода на `fast`. Корейский с `fast` или устаревшим псевдонимом `tesseract` отклоняется до постановки в очередь с `FEATURE_INCOMPATIBLE` и `fast-korean-unsupported`.
:::
<!-- korean-ocr-contract:end -->
## Архитектура {#architecture}

```
Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
 |
 +-- Isolated OCR runtime (persistent JSONL dispatcher)
 |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
 |
 `-- Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- 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» заменяет AI-список разрешённых скриптов на скрипты обработки документов (`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}

AI-модели упакованы по общему стеку зависимостей, а не по одному архиву на инструмент. Один пакет возможностей может включать несколько инструментов, если они используют одно семейство моделей, одни Python-колёса (wheels) или одни нативные библиотеки. Это позволяет держать релизный Docker-образ меньше и избегать хранения дубликатов одних и тех же моделей матирования фона, распознавания лиц, OCR, реставрации и речи.

Docker-образ поставляется вместе с приложением и общей средой выполнения. Крупные архивы моделей загружаются по требованию в постоянный том `/data/ai`, а затем повторно используются каждым инструментом, которому они нужны. Если пакет уже установлен, потому что его затребовал другой инструмент, включение нового зависимого инструмента не приводит к повторной загрузке этого пакета.

Большинству инструментов искусственного интеллекта требуется один или несколько пакетов функций, прежде чем они смогут работать. Пользовательский интерфейс администратора устанавливает их с помощью инструмента `POST /api/v1/admin/tools/:toolId/features/install`, который обрабатывает полный список пакетов, пропускает уже установленные пакеты и помещает в очередь только недостающие загрузки. Например, включение Passport Photo в новых очередях экземпляров `background-removal` и `face-detection`; включение его после фонового удаления уже установлено в очередях только `face-detection`. OCR является исключением, поскольку `fast` не требует упаковки; установите дополнительную точную среду выполнения через пользовательский интерфейс или `POST /api/v1/admin/features/ocr/install`.

| Пакет | Размер | Общая группа зависимостей | Инструменты, использующие его |
|--------|------|-------------------------|-------------------|
| `background-removal` | 4-5 GB | матирование фона rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
| `face-detection` | 200-300 MB | распознавание лиц и ключевых точек MediaPipe | blur-faces, red-eye-removal, smart-crop |
| `object-eraser-colorize` | 1-2 GB | инпейнтинг/аутпейнтинг LaMa и DDColor | erase-object, colorize, ai-canvas-expand |
| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, шумоподавление | upscale, enhance-faces, noise-removal |
| `photo-restoration` | 4-5 GB | конвейер устранения царапин и реставрации | restore-photo |
| `ocr` | ~208-234 Загрузка MiB / ~409-488 Установка MiB | Дополнительные модели RapidOCR 3.9.1, ONNX Runtime 1.20.1 и закрепленные модели PP-OCR | ocr, ocr-pdf (только `balanced` и `best`) |
| `transcription` | ~600 MB | модели преобразования речи в текст faster-whisper | transcribe-audio, auto-subtitles |

Инструменты с межпакетными зависимостями:

| Инструмент | Требуемые пакеты | Причина |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Удаляет фон, затем использует ключевые точки лица, чтобы обрезать кадр под правила для фото на паспорт и удостоверение личности. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Распознаёт лица перед применением улучшения GFPGAN или CodeFormer к выбранным областям лица. |

Инструмент доступен только в том случае, если установлены все необходимые пакеты, за исключением OCR: его встроенный уровень `fast` остается доступным без дополнительного пакета OCR. Частичные установки допустимы и обрабатываются постепенно: установленные пакеты используются повторно, отсутствующие пакеты отображаются как загрузки, а установки в очереди выполняются по одной, поэтому общая среда Python не изменяется одновременно.

### Точная установка среды выполнения OCR {#accurate-ocr-runtime-installation}

Точный OCR пакет — это специфичная для платформы среда выполнения для официального Linux  amd64 или Linux  arm64 контейнер. В сборке amd64 используется Python 3.12; сборка arm64 использует Python 3.11. Обе сборки запускают RapidOCR через `CPUExecutionProvider` ONNX Runtime, поэтому один и тот же пакет работает только на процессорах и на хостах NVIDIA Docker. Для точной среды выполнения требуется не менее 4 GiB эффективной памяти: настроенный лимит cgroup контейнера, в противном случае — память хоста. Система ниже указанного минимального уровня совместимости отклоняется перед загрузкой. Это требование не распространяется на встроенный Fast OCR. Сборки Bare-metal отклоняются, поскольку их libc и Python ABI не могут быть безопасно выведены; Быстрый OCR остается доступным, если хост предоставляет Tesseract и Ghostscript.

Необязательный артефакт имеет размер около 208–234 MiB в сжатом виде и 409–488 MiB в извлеченном виде, в зависимости от архитектуры. Подписанный индекс связывает точное количество сжатых и извлеченных байтов, заданное установщиком. Встроенный Tesseract добавляет к официальному образу около 25 MiB и не требует файлов в `/data/ai`.

При онлайн-установке извлекается подписанный индекс выпуска и точный артефакт с адресом содержимого для текущей платформы. SnapOtter проверяет подпись индекса Ed25519, размер артефакта, дайджест SHA-256, дайджесты модели, пути, режимы файлов и промежуточный smoke test перед атомарной активацией нового поколения. Неудачная установка оставляет активным предыдущее работоспособное поколение.

Для установки с воздушным зазором загрузите `ocr-runtime-index.json` выпуска и соответствующий архив времени выполнения OCR в `POST /api/v1/admin/features/import`, используя составные поля с именами `index` и `archive`. Автономный импорт применяет те же проверки подписи, хеша, извлечения, совместимости и дымового тестирования, что и онлайн-установка; архив без доверенного подписанного индекса отклоняется.

---

## Удаление фона {#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 (`fast`); RapidOCR с небольшими моделями PP-OCRv6 (`balanced`); Средние модели PP-OCRv6 с калиброванной оценкой вариантов (`best`)

| Параметр | Тип | По умолчанию | Описание |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамический | Если `quality` и `engine` не заданы, SnapOtter выбирает лучший доступный уровень в порядке `best`, `balanced`, `fast`. Для корейского языка `fast` никогда не выбирается: используется `best`, затем `balanced`, либо возвращается ошибка установки или совместимости точной среды выполнения. |
| `language` | string | `"auto"` | Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
| `enhance` | логическое значение | Зависит от уровня | Улучшите локальный контраст. Fast применяет его напрямую; точные уровни сохраняют вариант только тогда, когда калиброванная оценка улучшает OCR. По умолчанию включено в лучшем случае |
| `engine` | нить | - | Устаревший псевдоним совместимости. Сопоставляет `tesseract` с `fast`, а устаревшее значение `paddleocr` с `balanced`; не загружается PaddlePaddle |

Возвращает извлеченный текст, а также метаданные происхождения: механизм, запрошенное и фактическое качество, устройство, поставщик, состояние деградации, предупреждения и точные версии времени выполнения/модели, если применимо. Явные запросы на качество никогда не переходят на другой уровень. Если `balanced` или `best` недоступны, API возвращает `FEATURE_NOT_INSTALLED` или `FEATURE_INCOMPATIBLE` вместо автоматического запуска `fast`.

## OCR для PDF {#pdf-ocr}

**Маршрут инструмента:** `ocr-pdf`  
**Модели:** Та же система уровней, что и у OCR изображений

Извлекает текст из отсканированных PDF-документов с помощью AI-OCR, страница за страницей.

| Параметр | Тип | По умолчанию | Описание |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамический | Если `quality` и `engine` не заданы, SnapOtter выбирает лучший доступный уровень в порядке `best`, `balanced`, `fast`. Для корейского языка `fast` никогда не выбирается: используется `best`, затем `balanced`, либо возвращается ошибка установки или совместимости точной среды выполнения. |
| `language` | string | `"auto"` | Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
| `pages` | string | `"all"` | Выбор страниц: `"all"`, `"1-3"`, `"1,3,5"` |
| `enhance` | логическое значение | Зависит от уровня | Улучшите локальный контраст. Fast применяет его напрямую; точные уровни сохраняют вариант только тогда, когда калиброванная оценка улучшает OCR. По умолчанию включено в лучшем случае |
| `engine` | нить | - | Устаревший псевдоним совместимости. Сопоставляет `tesseract` с `fast`, а устаревшее значение `paddleocr` с `balanced`; не загружается PaddlePaddle |

То же правило запрета перехода на более раннюю версию применяется к PDF OCR. Страницы PDF перед распознаванием растрируются, и за один запрос можно выбрать не более 50 страниц.

## Размытие лиц / персональных данных {#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-раскрашивание {#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 | (обязательно) | Идентификатор задания из фазы 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` | Максимальный размер файла в KB (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 |

## Удаление объектов (инпейнтинг) {#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-расширение холста {#ai-canvas-expand}

**Маршрут инструмента:** `ai-canvas-expand`  
**Модель:** аутпейнтинг на базе LaMa

Расширяет холст изображения в любом направлении и заполняет новые области сгенерированным AI-содержимым, совпадающим с существующим изображением.

| Параметр | Тип | По умолчанию | Описание |
|-----------|------|---------|-------------|
| `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`  
**Модель:** BiRefNet HR-matting (разрешение 2048x2048)

Исправляет «псевдопрозрачные» PNG, где фон был удалён, но остались бахрома, ореолы или полупрозрачные артефакты. Использует высокоразрешающую модель матирования BiRefNet для создания чистого альфа-канала, затем применяет настраиваемую обработку удаления бахромы для устранения цветового загрязнения вдоль краёв.

**Цепочка запасных вариантов при нехватке памяти (OOM):** Если BiRefNet HR-matting превышает доступную память, инструмент автоматически переходит на `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"}'
```

---

## Инструменты с опциональными AI-возможностями {#tools-with-optional-ai-capabilities}

Следующие инструменты не являются инструментами Python-сайдкара, но используют AI-возможности, когда включены определённые опции.

### Улучшение изображений {#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` | Включить AI-удаление шума через 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` | Принудительный квадратный вывод |