SnapOtter/apps/docs/uk/api/rest.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Повний довідник REST API. Кінцеві точки інструментів, пакетна обробка, конвеєри, бібліотека файлів, автентифікація, команди й адміністративні операції.	20d37040e8ea	b89b5df16af5	human

Довідник REST API

Інтерактивна документація API з прикладами запитів і відповідей доступна за адресою http://localhost:1349/api/docs.

Машиночитні специфікації:

• /api/v1/openapi.yaml - специфікація OpenAPI 3.1
• /llms.txt - зручне для LLM резюме
• /llms-full.txt - повна зручна для LLM документація

Автентифікація

Усі кінцеві точки потребують автентифікації, окрім випадків, коли AUTH_ENABLED=false.

Токен сесії

# 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-ключі

# 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: неопрацьований ключ показується один раз і надалі його неможливо отримати.

Кінцеві точки автентифікації

Метод	Шлях	Доступ	Опис
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.

Дозволи

Дозвіл	Адмін	Користувач
Використання інструментів	✓	✓
Власні файли/конвеєри/API-ключі	✓	✓
Перегляд файлів/конвеєрів/ключів усіх користувачів	✓	-
Запис налаштувань	✓	-
Керування користувачами і командами	✓	-
Керування брендингом	✓	-

Перевірка стану

Метод	Шлях	Доступ	Опис
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.

Використання інструментів

Кожен інструмент дотримується однакового шаблону:

# 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 для відстеження прогресу, а потім завантажте результат після завершення (див. Відстеження прогресу).
• Пакетні маршрути повертають ZIP-архів, що передається напряму (із заголовком X-Job-Id), для інструментів, зареєстрованих у загальному пакетному реєстрі.

Довідник інструментів

Пресети конвертації

Спільний каталог містить 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. Повну таблицю маршрутів і необов'язкові налаштування див. у Пресети конвертації.

Основне

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

Оптимізація

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 - генерує всі стандартні розміри

Коригування

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-інструменти працюють на вашому обладнанні: 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 / Вилучення тексту	Tesseract (швидкий); RapidOCR + PP-OCR ONNX (збалансований/найкращий)	quality (швидкий/збалансований/найкращий), 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

Водяні знаки й накладення

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 з файлом).

Утиліти

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, без завантаження файлу.

Компонування й композиція

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 зображення)

Формат і конвертація

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)

Відеоінструменти

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)

Аудіоінструменти

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)

Інструменти для документів

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

Файлові інструменти

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 у зображення

Захоплення вебсторінки як зображення. На відміну від інших інструментів, ця кінцева точка приймає 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

Приклад:

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"}'

Відповідь:

{
  "jobId": "uuid",
  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
  "originalSize": 0,
  "processedSize": 54321
}

Підмаршрути інструментів

Деякі інструменти надають додаткові кінцеві точки понад стандартний 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	Легкий попередній перегляд для живого налаштування параметрів. Повертає оптимізоване зображення із заголовками розміру.

Пакетна обробка

Застосуйте загальний пакетний інструмент до кількох файлів одночасно. Повертає 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 для необмеженої кількості).

Конвеєри

Виконання конвеєра

# 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, щоб зняти обмеження.

Збереження конвеєрів і керування ними

Метод	Шлях	Опис
POST	/api/v1/pipeline/save	Зберегти іменований конвеєр (name, description, steps[])
GET	/api/v1/pipeline/list	Список збережених конвеєрів (адміни бачать усі; користувачі бачать власні)
DELETE	/api/v1/pipeline/:id	Видалити (власник або адмін)
GET	/api/v1/pipeline/tools	Список ID інструментів, дійсних для кроків конвеєра

Відстеження прогресу

Тривалі завдання, поставлені в чергу інструменти, пакетні завдання і конвеєри видають прогрес у реальному часі через Server-Sent Events. Потік прогресу є публічним і прив'язується за ID завдання, тож клієнтам не потрібно надсилати заголовок Authorization для його читання.

# 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}.

Бібліотека файлів

Постійне сховище файлів з історією версій.

Метод	Шлях	Опис
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-ключами

Метод	Шлях	Доступ	Опис
POST	/api/v1/api-keys	Автентиф.	Згенерувати новий ключ - показується один раз
GET	/api/v1/api-keys	Автентиф.	Список ключів (name, id, lastUsedAt - не неопрацьований ключ)
DELETE	/api/v1/api-keys/:id	Автентиф.	Видалити ключ

Команди

Метод	Шлях	Доступ	Опис
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)	Видалити команду (не можна видалити команду за замовчуванням або команди з учасниками)

Налаштування

Конфігурація ключ-значення в реальному часі (читає будь-який автентифікований користувач, записує лише адмін).

Метод	Шлях	Опис
GET	/api/v1/settings	Отримати всі налаштування
PUT	/api/v1/settings	Масове оновлення налаштувань (тіло JSON з парами ключ-значення)
GET	/api/v1/settings/:key	Отримати конкретне налаштування за ключем

Відомі ключі: disabledTools (JSON-масив ID інструментів), enableExperimentalTools (bool-рядок), loginAttemptLimit (число).

Уподобання

Уподобання окремих користувачів відокремлені від налаштувань екземпляра. Будь-який автентифікований користувач може читати й оновлювати власну карту уподобань.

Метод	Шлях	Опис
GET	/api/v1/preferences	Отримати уподобання поточного користувача як { "preferences": { ... } }
PUT	/api/v1/preferences	Вставити або оновити один чи кілька ключів уподобань для поточного користувача

Ролі

Керування власними ролями з детальними дозволами.

Метод	Шлях	Доступ	Опис
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.

Журнал аудиту

Кінцева точка лише для адміністраторів для перегляду дій, пов'язаних із безпекою.

Метод	Шлях	Доступ	Опис
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

Аналітика

Метод	Шлях	Доступ	Опис
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-набори

Керування наборами 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-моделями
POST	/api/v1/admin/features/import	Адміністратор (features:manage)	Імпортуйте застарілий пакет штучного інтелекту (file) або підписаний автономний випуск OCR (index плюс archive)

Імпорт OCR із повітряним проміжком має містити підписаний ocr-runtime-index.json випуску та відповідний архів платформи. SnapOtter застосовує ті самі перевірки підпису Ed25519, хешу артефакту, сумісності, вилучення та димового тесту, які використовуються під час онлайн-інсталяції:

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)
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

Ці маршрути ліцензійно обмежені пов'язаною корпоративною можливістю. Вони все одно потребують зазначеного дозволу 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 є публічними. Кінцеві точки користувачів і груп потребують 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	Видалити команду

Шаблони мемів

Допоміжний 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	Автентиф.	Надати файл шрифту, що використовується для рендерингу тексту мемів

Відповіді з помилками

Усі помилки повертають 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	Внутрішня помилка сервера