API reference/15 of 24

Compress

Shrink images and keep the original format.

POST/compress

Makes images smaller and keeps their format. Send files as multipart form data (up to your plan’s batch limit); each file counts as one image. The request returns when every file is done.

When you can change format, prefer convert to WebP or AVIF — that often shrinks photos more than same-format compress (see Best practices).

A file is never made bigger. If it can't shrink, you get the original back with "unchanged": true, and it isn't charged. The exception is a file with EXIF, XMP or IPTC metadata, which you asked us to remove: that's a 400 cannot_shrink, unless you send keep_metadata=true.

In a batch, a file that fails is left out of "files" and isn't charged; "images_used" is the number charged. If the only file fails, the request fails with that file's error.

Body (multipart/form-data)

  • files[]fileRequired

    1 or more images, up to your plan’s batch limit (5 on Free, 10 on Pro and Business). Max size per file depends on your plan.

  • qualitystring | integer

    "balanced" (default), "high" or "smallest". Pro and Business can also send a number from 1 to 100. Images are encoded at exactly this quality.

  • target_kbinteger

    Pro and Business. Aim for a file size from 10 to 102400 KB: quality becomes a ceiling and is lowered step by step until each file fits.

  • losslessboolean

    Pro and Business. Pixel-perfect output for WebP, AVIF, PNG and TIFF. GIF uses a max 256-colour palette (not pixel-perfect). Not available for JPEG.

  • maxWidthinteger

    Shrink wider images to this width. 640 to 2560 px; values outside are moved into that range. Never enlarges.

  • maxHeightinteger

    Shrink taller images to this height. 480 to 2560 px, moved into range the same way. With maxWidth, images fit inside the box.

  • keep_metadataboolean

    Keep EXIF and color profile data. Defaults to false: metadata, including GPS location, is removed.

curl https://api.comprestack.com/api/v1/compress \
  -H "Authorization: Bearer $COMPRESTACK_API_KEY" \
  -F "files[]=@hero-banner.png" \
  -F "files[]=@team-photo.jpg" \
  -F "quality=balanced"
Response
{
  "id": "job_4f1c9a2e7b3d5c8f0a6e1b9d",
  "object": "job",
  "mode": "compress",
  "status": "done",
  "format": null,
  "files": [
    {
      "index": 0,
      "name": "hero-banner.png",
      "original_size": 4820113,
      "size": 1032410,
      "saved_percent": 78.6,
      "unchanged": false,
      "width": 2400,
      "height": 1260,
      "format": "png"
    }
  ],
  "created_at": "2026-10-17T10:42:08.114Z",
  "expires_at": "2026-10-17T11:42:08.114Z",
  "images_used": 1,
  "usage": {
    "plan": "pro",
    "images_used": 1285,
    "images_limit": 2500,
    "pack_images": 500,
    "remaining": 1215
  },
  "download_url": "/api/v1/jobs/job_4f1c9a2e7b3d5c8f0a6e1b9d/download?token=8c2f…e71a"
}