Compresso API один запрос, лёгкая картинка

1. Войдите по email и скопируйте API-ключ в личном кабинете.
2. Выполните команду ниже со своим ключом и любым файлом PNG, JPEG или WebP.
3. photo-min.png и есть сжатая копия. Это вся интеграция.

curl https://api.compresso.space/v1/compress \
  --user api:YOUR_API_KEY \
  --data-binary @photo.png \
  --output photo-min.png \
  --fail-with-body

Если что-то пошло не так, curl завершится с ошибкой, а в photo-min.png окажется короткое JSON-сообщение: что случилось и как это исправить.

В Windows PowerShell пишите curl.exe вместо curl: там curl является псевдонимом другой команды.

Каждый запрос требует API-ключ. Передайте его через HTTP Basic auth, с любым именем пользователя и ключом в качестве пароля (curl --user api:ВАШ_КЛЮЧ), или в заголовке Authorization: Bearer. Оба способа работают везде.

Запросы принимаются только по HTTPS. Обычный HTTP отклоняется с ошибкой https_required, без перенаправления. Если ключ хоть раз ушёл по HTTP, отзовите его в кабинете и создайте новый.

Храните ключи на сервере. API отклоняет запросы со страниц в браузере (browser_not_supported), поэтому ключ не может попасть к вашим посетителям. У аккаунта может быть до 10 активных ключей, любой можно отозвать в любой момент.

curl https://api.compresso.space/v1/usage --user api:YOUR_API_KEY

Отправьте изображение методом POST на /v1/compress. Тело запроса: сами байты файла, либо форма multipart/form-data с изображением в поле file. Формат определяется по содержимому файла, поэтому Content-Type при отправке байтов не важен.

Успешный ответ и есть сжатое изображение: статус 200 и тот же формат, что вы отправили. Сохраните тело ответа как двоичный файл. Отдельного шага скачивания нет.

# raw bytes
curl https://api.compresso.space/v1/compress \
  --user api:YOUR_API_KEY \
  --data-binary @photo.png \
  --output photo-min.png \
  --fail-with-body

# or as a form upload (field "file")
curl https://api.compresso.space/v1/compress \
  --user api:YOUR_API_KEY \
  --form file=@photo.png \
  --output photo-min.png \
  --fail-with-body

Заголовки ответа

GET /v1/usage возвращает расход аккаунта, ничего не сжимая. Так удобно проверить, что ключ работает. Этот запрос не расходует лимит.

curl https://api.compresso.space/v1/usage --user api:YOUR_API_KEY

{
  "ok": true,
  "plan": "free",
  "compression_count": 3,
  "compression_limit": 100,
  "compression_reset": "2026-09-19T00:00:00Z",
  "key": "csk_…a1b2"
}

Отправляйте изображения по одному: у каждого аккаунта одновременно сжимается одно изображение и ещё одно ждёт, поэтому параллельные загрузки получат rate_limited. Если API отвечает 429 или 503 с заголовком Retry-After, подождите указанное число секунд и повторите. Без Retry-After повторять не нужно.

// Compress every PNG/JPEG/WebP in ./images into ./images-min, one at a time.
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"
import path from "node:path"

const KEY = process.env.COMPRESSO_API_KEY
const IN = "images"
const OUT = "images-min"
await mkdir(OUT, { recursive: true })

for (const name of await readdir(IN)) {
  if (!/\.(png|jpe?g|webp)$/i.test(name)) continue
  const body = await readFile(path.join(IN, name))

  for (;;) {
    const res = await fetch("https://api.compresso.space/v1/compress", {
      method: "POST",
      headers: { Authorization: `Bearer ${KEY}` },
      body,
    })
    if (res.ok) {
      await writeFile(path.join(OUT, name), Buffer.from(await res.arrayBuffer()))
      console.log(name, res.headers.get("Original-Size"), "->", res.headers.get("Compressed-Size"))
      break
    }
    const err = await res.json()
    // Retry only when the API says so, and only for short waits.
    const wait = Number(res.headers.get("Retry-After"))
    if (wait > 0 && wait <= 60) {
      await new Promise((r) => setTimeout(r, wait * 1000))
      continue
    }
    console.error(name, err.error, err.message)
    if (res.status === 429 || res.status === 503) process.exit(1) // limit or long outage
    break
  }
}

• PNG, JPEG и WebP сжимаются тем же движком и с той же попиксельной проверкой качества, что на compresso.space. Результат визуально неотличим от оригинала.
• Формат и размеры в пикселях не меняются. Ничего не уменьшается и не конвертируется.
• В сжатых изображениях нет метаданных (EXIF, GPS, данных камеры). Фото сначала поворачиваются по EXIF-ориентации, поэтому остаются в правильном положении.
• Если изображение нельзя уменьшить без видимой разницы, вы получите исходный файл без изменений, вместе с метаданными, со статусом 200. Такой запрос тоже считается сжатием.
• Изображения обрабатываются в памяти, не записываются на диск и не хранятся. Само изображение никогда не попадает в логи: для статистики мы сохраняем только размеры и формат.

• curl -d портит двоичные файлы. Всегда используйте --data-binary @файл или --form file=@файл.
• Не отправляйте base64, data:-ссылку или JSON со ссылкой на картинку. Отправляйте байты файла.
• В axios нужен responseType: "arraybuffer", иначе изображение прочитается как текст и испортится.
• В Python requests сохраняйте res.content (байты), а не res.text.
• Вызывайте API с сервера или из скриптов сборки, а не из JavaScript на странице: браузеры отклоняются намеренно.

Любая ошибка приходит в JSON: {"ok": false, "error": "код", "message": "...", "docs": "...", "request_id": "..."}. В message объяснено, что случилось и что делать, поэтому выводите его.

Правило повторов: если 429 или 503 пришли с заголовком Retry-After, подождите указанное число секунд и повторите. Без Retry-After автоматически не повторяйте.

Полное машиночитаемое описание API лежит по адресу https://api.compresso.space/v1/openapi.json (OpenAPI 3.1, ключ не нужен). Импортируйте его в Postman или Insomnia или сгенерируйте по нему клиент.

• 2026-09-18 Вышел API v1: /v1/compress, /v1/usage, 100 бесплатных сжатий в сутки.