API-СЖАТИЕ
ИЗОБРАЖЕНИЙ

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

Вход: JPEG/JPG, PNG и WebP. Поддерживаются только статичные изображения.

Результат: исходный формат (сжатие без конвертации), JPEG, PNG или WebP.

Из вашего списка API принимает JPG/JPEG, PNG и WebP; GIF и BMP API отклоняет. HEIC принимается браузерным инструментом сайта: браузер преобразует его в JPEG до отправки. Серверный API не декодирует HEIC. В браузере также доступны AVIF и JPEG XL как выходные форматы; API их пока не создаёт.

AVIF, JPEG XL, SVG, TIFF и любые другие форматы API не обрабатывает. Для неподдерживаемого типа сервер вернёт ошибку 415 Unsupported Media Type. Анимированные PNG и WebP также отклоняются; GIF не поддерживается независимо от анимации.

Лимиты одного файла: 5 МБ и 20 мегапикселей. Сервер сверяет MIME-тип и сигнатуру с форматом, проверяет, что декодер распознаёт содержимое, затем создаёт новый графический файл. Исходные байты не сохраняются и не выдаются обратно, поэтому встроенный исполняемый хвост или метаданные не переносятся в результат. Это проверка и очистка содержимого, а не антивирусное сканирование.

Ключ доступа

Создайте ключ в личном кабинете. Полное значение показывается только один раз. Передавайте его в заголовке Authorization и храните на своём сервере, а не во frontend-коде или публичном репозитории.

Запрос сжатия

Метод — POST, тип тела — multipart/form-data. Поле файла называется image, необязательное поле format принимает original, jpeg, png или webp. По умолчанию используется original. Необязательное поле billing_mode принимает standard или bitrix; по умолчанию действует standard.

Ниже указан намеренно нерабочий демонстрационный ключ. Это пример формата строки, он не выдавался пользователю и никогда не пройдёт авторизацию:

curl -X POST 'https://ank-tinypng.ru/api-compress.php' \
  -H 'Authorization: Bearer ank_test_DEMO_ONLY_NOT_A_REAL_KEY' \
  -F 'image=@photo.jpg' \
  -F 'format=webp' \
  --output photo.webp

Для реального запроса замените пример на действующий ключ и запускайте запрос из backend-приложения. Успешный ответ содержит бинарный файл и заголовки с исходным/итоговым размером и остатком лимита.

Списание для модуля Bitrix

Модуль ank.imagecompress передаёт billing_mode=bitrix и уникальный заголовок X-ANK-Request-ID из 64 шестнадцатеричных символов. Повтор одной и той же задачи обязан передавать тот же идентификатор. API сверяет отпечаток запроса и возвращает сохранённый результат без повторной тарификации; использование того же идентификатора для другого изображения или формата отклоняется ответом 409. Результаты повторов хранятся до 30 дней.

В этом режиме API проверяет сформированный файл и сравнивает его размер в байтах с отправленным изображением. Кредит списывается, только если результат валиден и строго меньше входного файла. Если результат равен входному или больше него, API всё равно возвращает результат, но стоимость запроса равна нулю.

Ответ содержит заголовки X-ANK-Billing-Mode, X-ANK-Request-ID, X-ANK-Result-Reduced, X-ANK-Credits-Cost, X-Original-Size и X-Optimized-Size. Модулю не нужно подтверждать сохранение файла в Bitrix. Если API выдало валидный уменьшенный результат, локальная ошибка сохранения или подключения файла не отменяет списание.

В обычном режиме standard размер результата не влияет на списание: успешная обработка стоит 1 кредит и при сжатии, и при конвертации.

Проверка доступности

Для проверки готовности сервиса используйте GET https://ank-tinypng.ru/api-health.php без API-ключа и файла. Этот запрос проверяет необходимые компоненты API и не обрабатывает изображение, не меняет данные и не расходует кредиты. Ответ 200 с {"status":"ok"} означает, что сервис готов; 503 с {"status":"unavailable"} — что проверка не пройдена. Для HEAD возвращается тот же HTTP-статус без тела ответа; другие методы получают 405.

Чтобы не создавать лишнюю нагрузку, модуль Bitrix проверяет доступность только при наличии ожидающих изображений и только пока API считается недоступным: не более трёх попыток за один запуск cron. После первого ответа 200 проверка прекращается, и запускается очередь изображений. Если все попытки неудачны, следующая проверка будет не раньше следующего часового запуска cron. Когда API уже доступен, повторно опрашивать его каждый час не нужно.

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

Чтобы проверить API-ключ и остаток лимитов, отправьте GET https://ank-tinypng.ru/api-balance.php с заголовком Authorization: Bearer <API_KEY>. Файл и параметры запроса не нужны. Действительный ключ получит ответ 200 только с числами остатков: free_remaining — бесплатные единицы до конца текущего календарного месяца, paid_credits — купленные кредиты, total_available — их сумма. Имена и email владельца не возвращаются. Запрос не запускает обработку, не меняет баланс и не списывает кредиты.

curl 'https://ank-tinypng.ru/api-balance.php' \
  -H 'Authorization: Bearer ank_test_DEMO_ONLY_NOT_A_REAL_KEY'

Пример ключа выше нерабочий; замените его действительным ключом. Неверный или отозванный ключ получает 401, превышение общего лимита 60 запросов в минуту на ключ — 429. Остальные ошибки возвращаются в JSON с полем error.

Стоимость и лимиты

• Первые 500 единиц API каждый календарный месяц — бесплатно; остаток не переносится.
• Одна успешная обработка стоит 1 кредит — и сжатие без смены формата, и конвертация, например JPEG в WebP.
• Купленные кредиты не сгорают. Пакеты указаны на странице тарифов.

Первые 500 обработок каждого календарного месяца доступны бесплатно. Дополнительные кредиты можно купить в личном кабинете; после подтверждения платежа Robokassa они автоматически добавляются к балансу.

Ошибки API

• 400 — отсутствует файл или запрос некорректен.
• 401 — ключ отсутствует, неверен или отозван.
• 402 — недостаточно бесплатных единиц и платных кредитов.
• 413 — превышен лимит размера файла или изображения.
• 415 — неподдерживаемый/повреждённый формат или анимация.
• 429 — превышен лимит 60 запросов в минуту на ключ.
• 503 — временная ошибка сервиса.

При ошибке возвращается JSON с полем error.