Compress Images API

Available

Lossy and lossless image compression, dimensional downscaling, EXIF stripping, and target file size optimization powered by libvips.

Try in Playground Product Page

Need general upload and polling mechanics?

See File Conversion for multipart upload (POST /api/uploads), status polling, and download token authentication.

View Guide

Same-Format Optimization & jobIntent

Standard conversions reject requests where the input and output formats are identical (e.g. JPG → JPG) as a no-op. Because compression optimizes the file in place, you must include "jobIntent": "transform" in your request body.

Supported Image Formats

OrbConvert accepts jpg, jpeg, png, webp, gif, svg, and tiff.

JPEG Compression

Fine-tuned DCT quantization matrices, progressive rendering, and EXIF profile removal.

PNG Quantization

Setting quality < 95 enables 8-bit palette quantization (TinyPNG method) yielding 60–80% size savings.

WebP Optimization

Supports both lossy WebP compression and pure lossless mode (lossless: true).

Request Specification

POST /api/conversions HTTP/1.1

Host: api.orbconvert.com

Authorization: Bearer <API_KEY>

Content-Type: application/json

{
  "fileId": "<FILE_ID>",
  "toFormat": "jpg",
  "jobIntent": "transform",
  "options": {
    "quality": 80,
    "stripMetadata": true,
    "progressive": true,
    "maxWidth": 1920
  }
}

Parameter	Type	Required	Description
fileId	string	Yes	The storage key returned by POST /api/uploads.
toFormat	string	Yes	Output format ('jpg', 'png', or 'webp'). Accepted: "jpg" \| "png" \| "webp"
jobIntent	string	Yes	Must be set to 'transform' for same-format compression. Accepted: "transform"
options.quality	integer	No	Image quality from 1 to 100. For PNG, quality < 95 applies palette reduction. Accepted: 1 – 100
options.targetSizeKb	integer	No	Target file size limit in kilobytes. The engine automatically balances quality to meet target. Accepted: 1 – 200,000
options.maxWidth	integer	No	Downscale width limit in pixels. Accepted: 16 – 20,000
options.maxHeight	integer	No	Downscale height limit in pixels. Accepted: 16 – 20,000
options.fit	string	No	Resize fit mode when dimensions are specified. Accepted: "inside" \| "cover" \| "fill" \| "outside"
options.stripMetadata	boolean	No	Strips EXIF, IPTC, and color profiles to reduce file footprint. Accepted: true \| false
options.progressive	boolean	No	Enables progressive JPEG scanning (JPEG only). Accepted: true \| false
options.lossless	boolean	No	Forces 100% lossless output encoding (PNG and WebP only). Accepted: true \| false

Image Compression Errors

HTTP	Error Code	Cause & Resolution
400	SAME_FORMAT_NOOP	Omitted jobIntent: 'transform' on a same-format request (e.g. jpg -> jpg).
400	OPTION_NOT_APPLICABLE	Requested progressive on a non-JPEG format, or lossless on a lossy format.
400	INVALID_OPTIONS	Quality, width, or targetSizeKb value was outside accepted numeric bounds.

Code Examples

# Compress an uploaded JPEG image in place
curl -X POST "https://api.orbconvert.com/api/conversions" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "<FILE_ID>",
    "toFormat": "jpg",
    "jobIntent": "transform",
    "options": {
      "quality": 80,
      "stripMetadata": true,
      "progressive": true
    }
  }'

Was this page helpful?