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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Полный справочник REST API. Эндпоинты инструментов, пакетная обработка, конвейеры, файловая библиотека, аутентификация, команды и административные операции.	b2ec4e36cb9f	7e0a0db4abe0	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 (tool routes are POST multipart)
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'

Сессии истекают через 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 -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'

Ключи имеют префикс si_ и хранятся как scrypt-хеши: необработанный ключ показывается один раз и после этого получить его повторно невозможно.

Эндпоинты аутентификации

Метод	Путь	Доступ	Описание
POST	/api/auth/login	Публичный	Вход, получение токена сессии
POST	/api/auth/logout	Auth	Уничтожение текущей сессии
GET	/api/auth/session	Auth	Проверка текущей сессии
POST	/api/auth/change-password	Auth	Смена собственного пароля (аннулирует все остальные сессии и API-ключи)
GET	/api/auth/users	Admin	Список всех пользователей
POST	/api/auth/register	Admin	Создание нового пользователя
PUT	/api/auth/users/:id	Admin	Обновление роли или команды пользователя
POST	/api/auth/users/:id/reset-password	Admin	Сброс пароля пользователя
DELETE	/api/auth/users/:id	Admin	Удаление пользователя
GET	/api/v1/config/auth	Публичный	Проверка, включена ли аутентификация ({ authEnabled: bool })
POST	/api/auth/mfa/enroll	Auth	Начало регистрации TOTP MFA. Требует enterprise-функцию mfa
POST	/api/auth/mfa/verify	Auth	Подтверждение регистрации MFA кодом TOTP
POST	/api/auth/mfa/complete	Публичный	Завершение ожидающего запроса на вход через MFA
POST	/api/auth/mfa/disable	Auth	Отключение MFA для текущего пользователя
POST	/api/auth/users/:id/mfa/reset	Admin (users:manage)	Сброс MFA для пользователя
GET	/api/auth/oidc/login	Публичный	Начало входа через OIDC, когда OIDC включён
GET	/api/auth/oidc/callback	Публичный	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.

Разрешения

Разрешение	Admin	User
Использование инструментов	✓	✓
Собственные файлы/конвейеры/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	Admin (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, когда доступен поддерживаемый графический процессор 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)	Маска отправляется как вторая файловая часть (fieldname 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	Контентно-зависимое изменение размера	Seam carving (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. Поток прогресса публичен и привязан к идентификатору задания, поэтому клиентам не нужно отправлять заголовок 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	Auth	Генерация нового ключа - показывается один раз
GET	/api/v1/api-keys	Auth	Список ключей (name, id, lastUsedAt - не необработанный ключ)
DELETE	/api/v1/api-keys/:id	Auth	Удаление ключа

Команды

Метод	Путь	Доступ	Описание
GET	/api/v1/teams	Admin (teams:manage)	Список команд
POST	/api/v1/teams	Admin (teams:manage)	Создание команды
PUT	/api/v1/teams/:id	Admin (teams:manage)	Переименование команды
DELETE	/api/v1/teams/:id	Admin (teams:manage)	Удаление команды (нельзя удалить команду по умолчанию или команды с участниками)

Настройки

Конфигурация среды выполнения использует закрытый набор распознаваемых ключей. Для чтения требуется settings:read, а для записи — settings:write; для ключей безопасности и соответствия дополнительно требуются security:manage или compliance:manage. Секретные настройки требуют полномочий администратора в полном объёме, а учётные данные и состояние, управляемые специализированными конечными точками, здесь доступны только для чтения. Пакетные обновления проверяются до записи любого значения.

Метод	Путь	Описание
GET	/api/v1/settings	Получить все настройки
PUT	/api/v1/settings	Массовое обновление настроек (тело JSON с парами «ключ-значение»)
GET	/api/v1/settings/:key	Получить конкретную настройку по ключу

Примеры ключей: disabledTools (JSON-массив идентификаторов инструментов), enableExperimentalTools (логическое значение), loginAttemptLimit (политика безопасности) и auditRetentionDays (политика соответствия). Неизвестные ключи отклоняются.

Предпочтения

Пользовательские предпочтения отделены от настроек экземпляра. Любой аутентифицированный пользователь может читать и обновлять собственную карту предпочтений.

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

Роли

Управление пользовательскими ролями с гранулярными разрешениями.

Метод	Путь	Доступ	Описание
GET	/api/v1/roles	Admin (audit:read)	Список всех ролей с количеством пользователей
POST	/api/v1/roles	Admin (security:manage)	Создание пользовательской роли (name, description, permissions)
PUT	/api/v1/roles/:id	Admin (security:manage)	Обновление пользовательской роли (нельзя изменять встроенные роли)
DELETE	/api/v1/roles/:id	Admin (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	Admin (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 и идентификатор экземпляра пусты, когда аналитика выключена, будь то из-за настройки на этапе компиляции или настройки экземпляра 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-бандлы

Управление бандлами 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-моделями
POST	/api/v1/admin/features/import	Администратор (features:manage)	Импортируйте устаревший пакет AI (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	Admin (settings:write)	Прочитать текущий уровень логирования во время выполнения
POST	/api/v1/admin/log-level	Admin (settings:write)	Изменить уровень логирования во время выполнения (fatal, error, warn, info, debug, trace или silent)
GET	/api/v1/metrics	Admin (system:health)	Метрики Prometheus в текстовом формате
GET	/api/v1/admin/support-bundle	Admin (system:health)	Загрузить отредактированный диагностический ZIP-бандл поддержки
GET	/api/v1/admin/usage	Admin (audit:read)	Данные панели использования, с необязательным параметром запроса days
GET	/api/v1/admin/backup-status	Admin (system:health)	Прочитать метаданные последнего резервного копирования и статус актуальности
POST	/api/v1/admin/backup-status	Admin (system:health)	Записать завершённое резервное копирование (type, необязательно sizeBytes, необязательно notes)

Enterprise API

Эти маршруты ограничены лицензией через связанную с ними enterprise-функцию. Они по-прежнему требуют указанного разрешения SnapOtter.

Встроенный администратор с полными правами — это прошедший аутентификацию субъект с ролью admin и полным набором действующих разрешений администратора. Область действия ключа API, в которой отсутствует хотя бы одно разрешение администратора, не соответствует этому требованию.

Метод	Путь	Доступ	Описание
GET	/api/v1/enterprise/audit/export	Admin (audit:read)	Экспорт записей аудита в JSON или CSV с фильтрами
GET	/api/v1/enterprise/config/export	Встроенный администратор с полными правами	Экспорт отредактированной конфигурации экземпляра, пользовательских ролей и команд
POST	/api/v1/enterprise/config/import	Встроенный администратор с полными правами	Импорт конфигурации, с необязательным пробным запуском
GET	/api/v1/enterprise/ip-allowlist	Admin (security:manage)	Прочитать настроенный список разрешённых CIDR
PUT	/api/v1/enterprise/ip-allowlist	Admin (security:manage)	Обновить список разрешённых CIDR с предотвращением самоблокировки
GET	/api/v1/enterprise/legal-hold	Admin (compliance:manage)	Список правовых блокировок пользователей и команд
PUT	/api/v1/enterprise/legal-hold	Admin (compliance:manage)	Применить или снять правовую блокировку с пользователя или команды
POST	/api/v1/enterprise/scim/token	Admin (users:manage)	Сгенерировать bearer-токен SCIM, возвращается один раз
DELETE	/api/v1/enterprise/scim/token	Admin (users:manage)	Отозвать текущий bearer-токен SCIM
GET	/api/v1/enterprise/siem/config	Admin (webhooks:manage)	Прочитать конфигурацию пересылки SIEM
PUT	/api/v1/enterprise/siem/config	Admin (webhooks:manage)	Обновить конфигурацию пересылки SIEM
GET	/api/v1/enterprise/webhooks	Admin (webhooks:manage)	Список назначений вебхуков
POST	/api/v1/enterprise/webhooks	Admin (webhooks:manage)	Создать назначение вебхука
PUT	/api/v1/enterprise/webhooks/:index	Admin (webhooks:manage)	Обновить назначение вебхука
DELETE	/api/v1/enterprise/webhooks/:index	Admin (webhooks:manage)	Удалить назначение вебхука
POST	/api/v1/enterprise/webhooks/:index/test	Admin (webhooks:manage)	Отправить тестовую полезную нагрузку вебхука
POST	/api/v1/enterprise/users/:id/export	Admin (compliance:manage)	Запустить задание экспорта пользователя по GDPR
GET	/api/v1/enterprise/users/:id/export/:jobId	Admin (compliance:manage)	Прочитать статус экспорта GDPR и URL для загрузки
DELETE	/api/v1/enterprise/users/:id/purge	Admin (compliance:manage)	Безвозвратно очистить данные пользователя после подтверждения
DELETE	/api/v1/enterprise/teams/:id/purge	Admin (compliance:manage)	Безвозвратно очистить данные команды после подтверждения
GET	/api/v1/admin/version	Admin (system:health)	Прочитать метаданные версии приложения, сборки, Node и схемы
GET	/api/v1/admin/migrations/pending	Admin (system:health)	Сравнить упакованные миграции с применёнными миграциями
GET	/api/v1/admin/upgrade-check	Admin (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	Auth	Список всех доступных шаблонов мемов с позициями текстовых полей
GET	/api/v1/meme-templates/full/:filename	Auth	Отдать полноразмерное изображение шаблона
GET	/api/v1/meme-templates/thumbs/:filename	Auth	Отдать миниатюру шаблона
GET	/api/v1/meme-templates/fonts/:filename	Auth	Отдать файл шрифта, используемый для отрисовки текста мема

Ответы с ошибками

Все ошибки возвращают 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	Внутренняя ошибка сервера