Free image compression API one request, a lighter image

1. Sign in with your email and copy your API key from the dashboard.
2. Run the command below with your key and any PNG, JPEG or WebP file.
3. photo-min.png is the compressed copy. That is the whole integration.

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

If something goes wrong, curl exits with an error and photo-min.png contains a short JSON message that says what happened and how to fix it.

On Windows PowerShell, type curl.exe instead of curl: plain curl there is an alias for a different command.

Node.js client

For Node projects there is an official client: no dependencies, TypeScript types included, and it retries the errors that are worth retrying. It also installs a compresso command for the terminal.

npm install compresso-api

Every request needs your API key. Send it with HTTP Basic auth, using any user name and the key as the password (curl --user api:YOUR_API_KEY), or in an Authorization: Bearer header. Both work everywhere.

Requests must use HTTPS. Plain HTTP is refused with https_required, never redirected. If a key was ever sent over plain HTTP, revoke it in your dashboard and create a new one.

Keep keys on the server. The API refuses requests that come from a web page in a browser (browser_not_supported), so a key can never be exposed to your visitors. You can have up to 10 active keys and revoke any of them at any time.

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

POST the image to /v1/compress. Send the raw file bytes as the request body, or a multipart/form-data upload with the image in a field named file. The format is detected from the file itself, so the Content-Type of a raw upload does not matter. Chunked uploads without a Content-Length work too, and hit the same size cap.

A successful response is the compressed image itself, with status 200 and the same format you sent. Save the body as a binary file. There is no second download step.

# 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

Response headers

GET /v1/usage returns your account's usage without compressing anything. It is a handy way to check that a key works. It does not count towards the limit.

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"
}

Send images one at a time: each account compresses one image at a time with one more waiting, so parallel uploads only get rate_limited. When the API answers 429 or 503 with a Retry-After header, wait that many seconds and try again. Without Retry-After, do not retry.

// 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 and WebP are compressed with the same engine and the same per-pixel quality gate as compresso.space. The result stays visually identical to the original.
• The format and the pixel dimensions never change. Nothing is resized or converted.
• Compressed images carry no metadata (EXIF, GPS, camera data). Photos are rotated according to their EXIF orientation first, so they stay upright.
• If an image cannot get smaller without a visible difference, you get the original file back unchanged, metadata included, with status 200. It still counts as a compression.
• Images are processed in memory and never written to disk or stored. The image itself is never logged: we keep only sizes and the format for statistics.

• curl -d mangles binary files. Always use --data-binary @file or --form file=@file.
• Do not send base64, a data: URL or JSON with an image link. Send the file bytes.
• axios needs responseType: "arraybuffer", otherwise the image is decoded as text and corrupted.
• In Python requests, write res.content (bytes), never res.text.
• Call the API from your server or build scripts, not from front-end JavaScript: browsers are refused on purpose.

Every error is JSON: {"ok": false, "error": "code", "message": "...", "docs": "...", "request_id": "..."}. The message explains what happened and what to do, so print it.

Retry rule: if a 429 or 503 carries a Retry-After header, wait that many seconds and retry. If there is no Retry-After, do not retry automatically.

The full machine-readable description of the API is at https://api.compresso.space/v1/openapi.json (OpenAPI 3.1, no key needed). Import it into Postman or Insomnia, or generate a client from it.

Is the Compresso API free?

Yes. Every account gets 100 compressions a day for free, reset at 00:00 UTC. You sign in with your email; no card is needed.

Do I need to download the result separately?

No. The compressed image comes back in the same response as your upload, so one request is all it takes. The response headers tell you the original size, the new size and how many compressions you have left today.

Which formats and sizes does it accept?

PNG, JPEG and WebP, up to 16 MB (16,777,216 bytes) and 16 megapixels per image. You get the same format back, with the same pixel dimensions.

Are my images stored?

No. Images are processed in memory and never written to disk or stored. The image itself is never logged; only sizes and the format are kept for statistics.

Do I need an SDK?

No. It is a plain HTTPS POST that any language can make. This page has ready examples for curl, Node.js, Python and PHP, and the OpenAPI description lets you generate a client or import it into Postman.

• 2026-09-18 API v1 released: /v1/compress, /v1/usage, 100 free compressions a day.