Когда для пользователя включён MFA, `POST /api/auth/login` возвращает `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` вместо токена сессии. Отправьте этот `mfaToken` вместе с кодом TOTP или кодом восстановления на `/api/auth/mfa/complete`.
### Разрешения {#permissions}
| Разрешение | Admin | User |
|-----------|:-----:|:----:|
| Использование инструментов | ✓ | ✓ |
| Собственные файлы/конвейеры/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` | Admin (`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`. Полную таблицу маршрутов и необязательные настройки см. в [Пресеты конвертации](/ru/tools/conversion-presets).
### Основное {#essentials}
| ID инструмента | Название | Ключевые настройки |
|---------|------|-------------|
| `resize` | Изменение размера | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, плюс 23 пресета для соцсетей |
Все AI-инструменты работают на вашем оборудовании: по умолчанию на CPU или на NVIDIA CUDA, когда доступен поддерживаемый графический процессор NVIDIA. Аппаратное ускорение iGPU Intel/AMD через VA-API, Quick Sync или OpenCL для AI-инференса сегодня не поддерживается. Интернет не требуется.
| ID инструмента | Название | AI-модель | Ключевые настройки |
| `passport-photo` | Фото на паспорт | Ориентиры MediaPipe | Двухфазный процесс. Анализ использует multipart `file`; генерация использует JSON с `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), ориентирами, размерами изображения |
| `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) - несколько файлов |
| `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/<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/passport-photo/analyze` | Фаза 1: AI-детекция лиц + удаление фона. Возвращает ориентиры лица и кешированные данные. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | Фаза 2: Обрезка, изменение размера и разбиение на плитки с использованием кешированного анализа. Без повторного запуска AI. |
| `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` | Лёгкое превью для настройки параметров в реальном времени. Возвращает оптимизированное изображение с заголовками размера. |
Применение общего инструмента с поддержкой пакетной обработки к нескольким файлам сразу. Возвращает ZIP-архив. Пользовательские многофайловые или многошаговые маршруты, такие как подписание PDF и маршруты пресетов PDF-в-изображение, используют собственный контракт эндпоинта вместо общего маршрута `/batch`.
Инструмент `ocr-pdf` поддерживает этот общий маршрут `/batch`.
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 \
Выход каждого шага является входом следующего шага. Конвейеры по умолчанию допускают 20 шагов, настраивается через `MAX_PIPELINE_STEPS`. Установите `MAX_PIPELINE_STEPS=0` для снятия ограничения.
### Сохранение и управление конвейерами {#save-and-manage-pipelines}
| `DELETE` | `/api/v1/pipeline/:id` | Удалить (владелец или администратор) |
| `GET` | `/api/v1/pipeline/tools` | Список ID инструментов, допустимых для шагов конвейера |
## Отслеживание прогресса {#progress-tracking}
Долго выполняющиеся задания, поставленные в очередь инструменты, пакетные задания и конвейеры передают прогресс в реальном времени через Server-Sent Events. Поток прогресса публичен и привязан к идентификатору задания, поэтому клиентам не нужно отправлять заголовок Authorization для его чтения.
```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
Вы можете запросить отмену поставленного в очередь или выполняющегося задания через `POST /api/v1/jobs/:jobId/cancel`. Ответом будет `{"canceled":true|false}`.
## Файловая библиотека {#file-library}
Постоянное хранилище файлов с историей версий.
| Метод | Путь | Описание |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | Загрузка файлов в рабочую область (временная обработка) |
| `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` | Auth | Генерация нового ключа - показывается один раз |
| `GET` | `/api/v1/api-keys` | Auth | Список ключей (name, id, lastUsedAt - не необработанный ключ) |
| `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` | Admin (`audit:read`) | Список всех ролей с количеством пользователей |
| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Создание пользовательской роли (`name`, `description`, `permissions`) |
Эндпоинт только для администраторов для просмотра действий, связанных с безопасностью.
| Метод | Путь | Доступ | Описание |
|--------|------|--------|-------------|
| `GET` | `/api/v1/audit-log` | Admin (`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 и идентификатор экземпляра пусты, когда аналитика выключена, будь то из-за настройки на этапе компиляции или настройки экземпляра `analyticsEnabled`. |
| `POST` | `/api/v1/feedback` | Auth | Отправить явную обратную связь пользователя в настроенный проект PostHog как `feedback_submitted`. Маршрут учитывает шлюз аналитики, ограничивает частоту отправок, удаляет контактные поля, если `contactOk` не равно true, и никогда не принимает содержимое файлов, имена файлов, пути загрузки или необработанный текст приватных ошибок. Когда аналитика отключена, он возвращает `{ "ok": true, "accepted": false }`. |
| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Установить отказ на уровне всего экземпляра. Отправьте тело JSON `{ "analyticsEnabled": "false" }`, чтобы отключить аналитику для всех, или `"true"`, чтобы снова включить её. |
## Функции / AI-бандлы {#features-ai-bundles}
Управление бандлами AI-функций (установка/удаление пакетов AI-моделей в среде Docker). Предпочтительнее использовать эндпоинт установки на уровне инструмента при включении инструмента из пользовательской автоматизации: некоторым AI-инструментам нужно более одного общего бандла, и этот эндпоинт пропускает уже установленные бандлы, ставя в очередь только недостающие.
OCR — это необязательное расширение, а не жесткая зависимость. Его уровень `fast` Tesseract работает без пакета; `POST /api/v1/admin/features/ocr/install` устанавливает подписанный пакет RapidOCR для `balanced` и `best` на Linux amd64 или arm64. Точная среда выполнения OCR использует CPU на хостах только с ЦП и NVIDIA и требует не менее 4 GiB эффективной памяти (настроенный предел cgroup контейнера, в противном случае память хоста). SnapOtter сообщает о `requiredMemoryBytes`, `effectiveMemoryBytes` и причине совместимости `insufficient-memory` и отклоняет несовместимую установку перед загрузкой. Это требование к памяти не применяется к `fast`. Пакет составляет около 208-234 MiB для загрузки и 409-488 MiB для установки, в зависимости от цели; подписанный индекс связывает точные размеры, применяемые во время установки.
| `GET` | `/api/v1/features` | Auth | Список всех бандлов функций и их статуса установки |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Установить бандл функции (асинхронно, возвращает `jobId` для отслеживания прогресса) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Установить каждый бандл, который требуется инструменту; возвращает статус queued/skipped по каждому бандлу |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Удалить бандл функции и очистить файлы моделей |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Получить общее использование диска AI-моделями |
Импорт OCR с воздушным зазором должен включать подписанный `ocr-runtime-index.json` выпуска и соответствующий архив платформы. SnapOtter применяет ту же подпись Ed25519, хэш артефакта, совместимость, извлечение и дымовые тесты, которые используются при онлайн-установке:
```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
-H "Authorization: Bearer <admin-token>"\
-F "index=@ocr-runtime-index.json"\
-F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```
Используйте архив `linux-arm64-cpu-py311` на arm64. Подписанный артефакт для другой цели скорее отклоняется, чем устанавливается.
Операционные эндпоинты для наблюдаемости, поддержки, отчётности об использовании и статуса резервного копирования.
| Метод | Путь | Доступ | Описание |
|--------|------|--------|-------------|
| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Прочитать текущий уровень логирования во время выполнения |
| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Изменить уровень логирования во время выполнения (`fatal`, `error`, `warn`, `info`, `debug`, `trace` или `silent`) |
