Главный вывод: SmartSlim Server предоставляет RESTful API с четырьмя основными интерфейсами — загрузка со сжатием, пакетное сжатие, запрос статуса, callback-уведомления — и поддерживает два способа аутентификации: API Key и Bearer Token. Загрузка и сжатие одного PDF-файла объёмом 100 МБ занимает около 8 секунд, пакетное сжатие 100 файлов — около 12 секунд. По умолчанию установлен лимит 60 запросов в минуту, в корпоративной версии его можно увеличить до 300. В этой статье — подробные таблицы параметров для четырёх интерфейсов, примеры вызова на Python / JavaScript / curl и схемы обработки ошибок. Ниже мы начнём с обзора API и подробно разберём каждый интерфейс.
Если вам нужна локальная интеграция через SDK, а не вызовы по HTTP, рекомендуем сначала прочитатьРуководство по интеграции Compression SDK: вызовы на Python / Java / C#。
1. Обзор API-интерфейсов
RESTful API SmartSlim Server разработан на фреймворке FastAPI: все интерфейсы возвращают данные в формате JSON и поддерживают загрузку файлов через multipart/form-data. Базовый путь API — /api/v1/, каждый запрос должен содержать учётные данные.
| Интерфейс | Метод | Путь | Назначение | Синхронный/Асинхронный |
|---|---|---|---|---|
| Загрузка со сжатием | POST | /api/v1/compress | Загрузка одного файла и сжатие | Синхронный (до 50 МБ) / асинхронный |
| Пакетное сжатие | POST | /api/v1/compress/batch | Загрузка нескольких файлов и пакетное сжатие | Асинхронный |
| Запрос статуса | GET | /api/v1/status/{task_id} | Запрос статуса задачи сжатия | Синхронный |
| Callback-уведомление | POST | URL обратного вызова клиента | Активное уведомление по завершении сжатия | Асинхронная отправка |
Есть два способа аутентификации: API Key подходит для серверных вызовов, Bearer Token — для вызовов с фронтенда. В таблице ниже сравниваются особенности обоих способов.
| Способ | Заголовок | Срок действия | Сценарий | Безопасность |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | Постоянно (можно отозвать) | Серверные вызовы | Средняя (требуется HTTPS) |
| Bearer Token | Authorization: Bearer token | 24 часа | Вызовы с фронтенда | Высокая (короткий срок) |
2. Подробное описание параметров интерфейсов
1. Интерфейс загрузки со сжатием
Интерфейс принимает один файл и возвращает результат сжатия. Для файлов до 50 МБ ответ возвращается синхронно со ссылкой на скачивание, для файлов свыше 50 МБ — асинхронно с идентификатором задачи.
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
| file | multipart/file | Да | - | Сжимаемый файл |
| format | string | Нет | Автоопределение | Тип файла (pdf/image/ofd) |
| level | string | Нет | medium | Уровень сжатия (low/medium/high/ultra) |
| quality | integer | Нет | 75 | Фактор качества (1–100) |
| callback_url | string | Нет | - | URL асинхронного callback-уведомления |
2. Интерфейс пакетного сжатия
Интерфейс принимает несколько файлов, обрабатывает их асинхронно и возвращает идентификатор пакетной задачи. Можно задать число параллельных потоков; максимум определяется лицензией.
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
| files | multipart/file[] | Да | - | Список сжимаемых файлов (до 100) |
| level | string | Нет | medium | Уровень сжатия |
| quality | integer | Нет | 75 | Фактор качества |
| workers | integer | Нет | 4 | Число параллельных потоков (1–16) |
| callback_url | string | Нет | - | URL callback-вызова по завершении |
3. Интерфейс запроса статуса
Этот интерфейс по идентификатору задачи возвращает текущее состояние и результат асинхронной задачи сжатия.
| Возвращаемое поле | Тип | Описание |
|---|---|---|
| task_id | string | Уникальный идентификатор задачи |
| status | string | Состояние (pending/processing/completed/failed) |
| progress | integer | Процент выполнения (0–100) |
| download_url | string | Ссылка на скачивание результата (после завершения) |
| original_size | integer | Исходный размер файла (в байтах) |
| compressed_size | integer | Размер после сжатия (в байтах) |
| error | string | Сообщение об ошибке (при сбое) |
3. Примеры вызова на трёх языках
Ниже приведены примеры вызова на curl, Python и JavaScript — все для загрузки и сжатия одного PDF-файла.
| Язык | Ключевой код | Описание |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | Вызов из командной строки |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | Библиотека requests |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
4. Ограничение скорости и обработка ошибок
API имеет продуманные механизмы ограничения скорости и обработки ошибок. Чтобы писать надёжный код, важно понимать коды состояния HTTP и коды ошибок.
| Код состояния HTTP | Код ошибки | Значение | Рекомендуемая реакция |
|---|---|---|---|
| 200 | - | Успех | Разобрать ответ |
| 400 | INVALID_PARAM | Неверный параметр | Проверить параметры запроса |
| 401 | UNAUTHORIZED | Сбой аутентификации | Проверить API Key / Token |
| 413 | FILE_TOO_LARGE | Файл превышает лимит | Использовать поблочную загрузку |
| 429 | RATE_LIMITED | Слишком частые запросы | Экспоненциальный повтор |
| 500 | INTERNAL_ERROR | Ошибка сервера | Повторить или обратиться в поддержку |
| 503 | SERVICE_UNAVAILABLE | Сервис недоступен | Повторить через некоторое время |
Подробности политики ограничения скорости: по умолчанию 60 запросов в минуту, до 10 одновременных в секунду; в корпоративной версии — 300 в минуту и до 30 в секунду. При превышении лимита возвращается код 429; в заголовках ответа присутствуют X-RateLimit-Remaining (оставшееся число запросов) и X-RateLimit-Reset (метка времени сброса). На стороне клиента рекомендуется реализовать экспоненциальный откат: при получении 429 — повтор через 1 секунду, далее через 2 и 4 секунды, максимум 3 попытки.
| Тип файла | Исходный размер | Размер после сжатия | Время сжатия | Степень сжатия |
|---|---|---|---|---|
| PDF (скан) | 80 МБ | 8,2 МБ | 6,5 с | 89,8% |
| PDF (электронный) | 15 МБ | 3,1 МБ | 1,2 с | 79,3% |
| JPEG-изображение | 12 МБ | 2,8 МБ | 0,8 с | 76,7% |
| PNG-изображение | 25 МБ | 6,5 МБ | 1,5 с | 74,0% |
| OFD-документ | 30 МБ | 5,2 МБ | 2,0 с | 82,7% |
Если хотите понять устройство очереди задач сжатия на нижнем уровне, см. статьюПроектирование очереди задач сжатия。Если нужно развернуть API-сервис в Docker, см. статьюРазвёртывание сервиса сжатия в Docker。
5. Часто задаваемые вопросы (FAQ)
В1: Как аутентифицировать вызовы Compression API?
API сжатия SmartSlim Server поддерживает два способа аутентификации: API Key (ключ передаётся в заголовке X-API-Key — подходит для серверных вызовов) и Bearer Token (JWT-токен передаётся в заголовке Authorization — подходит для вызовов с фронтенда). API Key действует бессрочно, но может быть отозван; срок действия токена — 24 часа, его нужно периодически обновлять. В производственной среде рекомендуется API Key — он проще и надёжнее.
В2: Какие форматы файлов поддерживает Compression API?
API серверной версии SmartSlim поддерживает PDF, изображения (jpg/jpeg/tif) и OFD с лимитом 1 ГБ на файл. API сетевой версии поддерживает все 10 категорий — более 40 форматов (включая видео, аудио, Office-документы) с лимитом 10 ГБ на файл. Тип файла можно указать параметром format; если он не задан, формат определяется автоматически. Обратите внимание: серверная версия поддерживает только PDF/изображения/OFD; для полного набора форматов нужна сетевая версия.
В3: Есть ли ограничение на частоту вызовов Compression API?
Да, для защиты стабильности сервиса действует политика ограничения скорости. По умолчанию: 60 запросов в минуту, до 10 одновременных в секунду. При превышении возвращается код 429; в заголовках ответа — X-RateLimit-Remaining и X-RateLimit-Reset. В корпоративной версии лимиты повышаются до 300 в минуту и 30 в секунду. На клиенте рекомендуется реализовать экспоненциальный откат: получив 429, повторять через 1, 2, 4 секунды.
В4: Как API обрабатывает большие файлы?
Для больших файлов (свыше 50 МБ) рекомендуется использовать интерфейс поблочной загрузки: файл делится на блоки по 5 МБ, после загрузки всех блоков отправляется уведомление о сборке и сжатии. После завершения результат можно получить через callback-уведомление или опрос статуса. Сжатие больших файлов идёт асинхронно и не блокирует API. PDF объёмом 100 МБ сжимается примерно за 8 секунд, видео 1 ГБ — около 90 секунд; по завершении автоматически формируется ссылка на скачивание.
Заключение
RESTful API SmartSlim Server предоставляет 4 основных интерфейса — загрузка со сжатием, пакетное сжатие, запрос статуса, callback-уведомления — и покрывает все сценарии от одиночных файлов до пакетной обработки. Аутентификация — на выбор: API Key для серверной стороны, Bearer Token для фронтенда. Политика ограничения скорости прозрачна: по умолчанию 60 запросов в минуту, в корпоративной версии — 300; при получении кода 429 — экспоненциальный откат. Скан PDF объёмом 80 МБ сжимается до 8,2 МБ за 6,5 секунды — степень сжатия 89,8%.
Запомните три момента: во-первых, для файлов до 50 МБ результат возвращается синхронно, для больших — асинхронно через идентификатор задачи; во-вторых, при получении 429 реализуйте экспоненциальный откат, а не жёсткий повтор; в-третьих, для больших файлов используйте интерфейс поблочной загрузки с блоками по 5 МБ. С правильным выбором интерфейса и параметров работа с Compression API проста. Если вы предпочитаете локальную интеграцию через SDK вместо HTTP, см. руководство по интеграции Compression SDK.
Похожие материалы
Нужно сжать файлы? Попробуйте SmartSlim
На основе собственного движка сжатия на Rust поддерживает PDF, изображения, видео, Office, OFD — более 40 форматов в 10 категориях; локальное сжатие без передачи данных за периметр.