description:"Повний довідник REST API. Кінцеві точки інструментів, пакетна обробка, конвеєри, бібліотека файлів, автентифікація, команди й адміністративні операції."
Коли для користувача ввімкнено 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 пресети для соцмереж |
Усі AI-інструменти працюють на вашому обладнанні: CPU за замовчуванням або NVIDIA CUDA, коли доступний підтримуваний GPU NVIDIA. Прискорення на iGPU Intel/AMD через VA-API, Quick Sync або OpenCL наразі не підтримується для AI-інференсу. Інтернет не потрібен.
| ID інструмента | Назва | AI-модель | Ключові налаштування |
| `passport-photo` | Фото на паспорт | Орієнтири MediaPipe | Двофазний процес. Аналіз використовує multipart `file`; генерація використовує JSON з `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), орієнтирами, розмірами зображення |
| `content-aware-resize` | Зміна розміру з урахуванням вмісту | Виріз швів (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
| `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` - другий файл є ціллю порівняння |
| `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/strip-metadata/inspect` | Перевіряє поля метаданих перед видаленням |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Фаза 1: AI-виявлення облич + видалення фону. Повертає орієнтири обличчя і кешовані дані. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | Фаза 2: Обрізання, зміна розміру і тайлинг з використанням кешованого аналізу. Без повторного запуску AI. |
Застосуйте загальний пакетний інструмент до кількох файлів одночасно. Повертає 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. Потік прогресу є публічним і прив'язується за ID завдання, тож клієнтам не потрібно надсилати заголовок 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` | Завантажити файли в робочу область (тимчасова обробка) |
| `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 - не неопрацьований ключ) |
Конфігурація середовища виконання використовує закритий набір розпізнаваних ключів. Для читання потрібен дозвіл `settings:read`, а для запису — `settings:write`; ключі безпеки та відповідності додатково вимагають `security:manage` або `compliance:manage`. Секретні налаштування вимагають повноважень повного адміністратора, а облікові дані та стан, якими керують спеціалізовані кінцеві точки, тут доступні лише для читання. Пакетні оновлення перевіряються до запису будь-якого значення.
Уподобання окремих користувачів відокремлені від налаштувань екземпляра. Будь-який автентифікований користувач може читати й оновлювати власну карту уподобань.
| Метод | Шлях | Опис |
|--------|------|-------------|
| `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`) |
Кінцева точка лише для адміністраторів для перегляду дій, пов'язаних із безпекою.
| Метод | Шлях | Доступ | Опис |
|--------|------|--------|-------------|
| `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-інструменти потребують більш ніж одного спільного набору, а ця кінцева точка пропускає вже встановлені набори, ставлячи в чергу лише відсутні.
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` | Автентиф. | Список усіх наборів можливостей та їхнього статусу встановлення |
| `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-моделями |
Імпорт 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` | Адмін (`settings:write`) | Прочитати поточний рівень журналювання середовища виконання |
| `POST` | `/api/v1/admin/log-level` | Адмін (`settings:write`) | Змінити рівень журналювання середовища виконання (`fatal`, `error`, `warn`, `info`, `debug`, `trace` або `silent`) |
**Вбудований адміністратор із повними правами** означає, що автентифікований суб’єкт має роль `admin` і повний набір фактичних дозволів адміністратора. Область дії ключа API, у якій відсутній хоча б один дозвіл адміністратора, не відповідає цій вимозі.
| `GET` | `/api/v1/enterprise/config/export` | Вбудований адміністратор із повними правами | Експортувати відредаговану конфігурацію екземпляра, власні ролі й команди |
| `POST` | `/api/v1/enterprise/config/import` | Вбудований адміністратор із повними правами | Імпортувати конфігурацію, з необов'язковим пробним запуском |
