Документация

От быстрого старта до тонкой настройки.
Всё, что нужно знать для работы с LW Compress

⚡

Быстрый старт

Сжатие первого файла за 2 минуты
🖼

Форматы

PNG, JPEG, WebP, AVIF, JPEG XL — что выбрать
🔌

REST API

Справочник эндпоинтов
🚀

Выделенные мощности

Сервер без общей очереди — Pro

Быстрый старт

Через веб-интерфейс

  1. Откройте little-white.by/compress
  2. Перетащите изображения в зону загрузки (или нажмите «выберите файлы»)
  3. Выберите формат и качество при необходимости
  4. Скачайте результат — один файл или ZIP-архив
Без регистрации: до 50 файлов в день, макс. 2 МБ на файл. Для больших объёмов подключите тариф Pro.

Через API (Pro)

  1. Зарегистрируйтесь на little-white.by и подключите тариф Pro
  2. Получите API-ключ в личном кабинете
  3. Отправьте запрос:
# Node.js const form = new FormData(); form.append('file', fs.createReadStream('photo.jpg')); form.append('format', 'avif'); const res = await fetch('https://little-white.by/compress/v1/compress', { method: 'POST', headers: { Authorization: 'Bearer sk-lw-ваш-ключ' }, body: form }); const buffer = await res.arrayBuffer(); fs.writeFileSync('result.avif', Buffer.from(buffer));
# Python import requests res = requests.post( 'https://little-white.by/compress/v1/compress', headers={'Authorization': 'Bearer sk-lw-ваш-ключ'}, files={'file': open('photo.jpg', 'rb')}, data={'format': 'avif'} ) with open('result.avif', 'wb') as f: f.write(res.content)

Поддерживаемые форматы

На вход принимаются JPEG, PNG и WebP. На выходе — любой из пяти форматов:

PNG

Сохраняет прозрачность. Лучший выбор для иконок и UI-элементов.

~60–80% экономии

JPEG

Trellis quantization — визуально лучше стандартного JPEG при меньшем размере.

~40–60% экономии

WebP

Поддержан всеми современными браузерами. Хороший баланс размера и качества.

~50–70% экономии

AVIF

Формат нового поколения. Лучшее соотношение качество/размер. Chrome, Firefox, Safari 16+.

~60–80% экономии

JPEG XL

Замена JPEG от JPEG Committee. Поддерживает прозрачность, HDR, lossless. Chrome 91+, Safari 17+.

~50–70% экономии

Какой формат выбрать?

Задача Рекомендация Почему
Фото на сайте AVIF + JPEG fallback Лучшее сжатие, поддержка >95% браузеров через <picture>
E-commerce каталог WebP 100% поддержка, быстрое кодирование, хорошее качество
Иконки и UI PNG Прозрачность, чёткие линии
Максимальная экономия AVIF Минимальный размер при сохранении визуального качества
Архивное хранение JPEG XL (lossless) Lossless + HDR + прозрачность в одном формате
Режим «Оригинал» сжимает файл в исходном формате без конвертации. Подходит, когда важно сохранить совместимость.

Webhook-уведомления

Когда пакетная обработка (POST /v1/batch, тариф Pro) завершится, сервис отправит POST-запрос на ваш адрес. Адрес передаётся в запросе параметром webhook_url или задаётся в личном кабинете (раздел «Уведомления» → «Webhook-уведомления»). Адрес из запроса важнее адреса из кабинета.

Адрес должен быть публичным: только http или https, порты 80, 443, 8080, 8443; внутренние адреса не принимаются, перенаправления не выполняются. Если ваш сервер ответит кодом 5xx или не ответит, запрос повторится до трёх раз.

Формат уведомления

POST https://your-server.com/webhook Content-Type: application/json X-LW-Event: batch.done X-LW-Timestamp: 1760450000 X-LW-Signature: sha256=abc123... { "event": "batch.done", "job_id": "0b6f1c2e-6c1d-4f8e-9a51-3d2f6c7b8a90", "status": "done", "total": 20, "completed": 19, "failed": 1, "status_url": "https://little-white.by/compress/v1/jobs/0b6f1c2e-6c1d-4f8e-9a51-3d2f6c7b8a90" }

Результаты забирайте запросами GET /v1/jobs/{job_id} и GET /v1/jobs/{job_id}/files/{index} с тем же ключом API. Результаты хранятся до 1 часа.

Проверка подписи

Подпись — HMAC-SHA256 от строки <X-LW-Timestamp>.<тело запроса>, ключ — ваш ключ API. Тело берите в том виде, в каком оно пришло, до разбора JSON. Если ключ перевыпущен, уведомления по уже запущенным заданиям подписаны прежним ключом.

const crypto = require('crypto'); function verifyWebhook(rawBody, headers, apiKey) { const ts = headers['x-lw-timestamp']; const sig = String(headers['x-lw-signature'] || ''); if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const expected = 'sha256=' + crypto .createHmac('sha256', apiKey) .update(ts + '.' + rawBody) .digest('hex'); return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); }
Безопасность: всегда проверяйте подпись и время (разница не больше 5 минут). Это защищает от подделки и повторной отправки уведомлений.

IP-whitelist

Ограничьте использование API-ключа списком доверенных IP-адресов. Настраивается в личном кабинете или через API:

curl -X PUT https://little-white.by/compress/v1/ips \ -H "Authorization: Bearer sk-lw-ваш-ключ" \ -H "Content-Type: application/json" \ -d '{"ips": ["203.0.113.10", "198.51.100.0/24"]}'

Поддерживаются отдельные IP и CIDR-подсети. Пустой массив — доступ с любого IP (whitelist отключён).

Лимиты и квоты

Параметр Free Pro
Сжатий в день 50 500
Макс. размер файла 2 МБ 10 МБ
Макс. сторона картинки 4000 px 8000 px
Rate limit (сжатие) 60 запросов / минута (per IP)
Batch-запросы — до 20 файлов
Мощности обработки Общая очередь Выделенный сервер — без общей очереди
Хранение результата 1 час после обработки

При превышении лимита API возвращает 429 Too Many Requests. Текущее использование доступно через GET /v1/limits.

Картинка, у которой большая сторона длиннее 4000 px (Free и без регистрации) или 8000 px (Pro), отклоняется с ответом 400: в поле error — её размер и предел, в поле code — image_too_large. Предел не зависит от веса файла: даже лёгкий файл может быть слишком большим по сторонам. Если обработка заняла слишком много времени, ответ — 422 с кодом processing_timeout.

Безопасность

  • API-ключи хранятся на сервере как хэши и в зашифрованном виде; ключ шифрования хранится отдельно от базы данных — копия базы ключей не раскрывает
  • Webhook-подписи — HMAC-SHA256 ключом API по строке «время.тело», проверка времени
  • SSRF-защита — webhook URL проверяется на приватные диапазоны
  • Decompression bomb — предел сторон картинки и времени обработки
  • Rate limiting — per-IP и per-key
  • Файлы автоматически удаляются через 1 час после обработки