Compresso 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.

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.

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.

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