Compression API — Free Tier + Pay-As-You-Go

Yes, for video and audio: send `targetSize=25` (MB, 1-500) with `toolOperation=video-compressor` or one of the audio compression operations. The engine probes the duration, takes `targetMB × 8192 ÷ duration_seconds` as the total kbps, trims 5% for container and rate-control overhead, subtracts the audio allowance to get the video bitrate, encodes two-pass, then stats the file it actually wrote. The audio allowance follows a quality ladder (128 kbps stereo down to 48 kbps mono) and steps down that ladder whenever a richer rung would leave the video under its ~100 kbps floor, so a size is only refused when even the cheapest audio rung cannot fit. If it came out over, it re-encodes at a bitrate scaled by the measured overshoot — at most two retries — and steps the resolution and frame rate down when the corrected bitrate falls under the ~100 kbps video floor. The job only completes when `result.outputSize` is at or under your ceiling. `targetSize` is rejected with a 400 on any other operation (including `compress-pdf` and `image-compressor`) rather than silently ignored, so you never get a false positive.

The job fails with `TARGET_SIZE_INFEASIBLE` and tells you roughly how much video would fit — for example, a 10-minute clip into 8 MB works out below the usable bitrate floor, and the error says about 7 minutes is the most 8 MB can hold. If the encoder still overshoots after all the retries you get `TARGET_SIZE_NOT_REACHED` with the best size achieved. Both are terminal and not retried, because the same request would fail the same way. What you will never get is a completed job whose output is bigger than the ceiling you asked for.

Audio is a fixed cost taken out of the video's share, so it scales with the total budget: 128 kbps stereo when the budget is roomy, then 96 and 64 kbps stereo, then 64 and 48 kbps mono at the bottom. A 25 MB ceiling on a 10-minute video leaves about 324 kbps total, so audio lands at 64 kbps stereo and video gets the remaining 260 kbps. Pass `audioBitrate` to override the ladder, or `removeAudio=true` to give the entire budget to video.

Scanned PDFs usually give the biggest win because the payload is embedded raster images and `pdfQuality=ebook` downsamples them to 150 DPI. Born-digital PDFs (LaTeX, InDesign exports) give much less — the savings come from font subsetting, duplicate-image detection and dropping unused objects. Text and vector art stay as text and vectors; Ghostscript rewrites the file, it does not rasterise the page.

It always re-encodes — that's where the size reduction comes from. `twoPass=true` runs two passes at a fixed bitrate derived from the quality tier and the output resolution (roughly 2500k / 1500k / 900k at 640x360, scaled by pixel count), so it targets a bitrate, not a file size. Use `targetSize` when you need the file size itself pinned; it runs its own two-pass encode at a duration-derived bitrate and verifies the result. If you only want a container change with no re-encode, use the Video Conversion API instead.

No. The image compression path re-encodes through Sharp without copying metadata, so EXIF, GPS coordinates and ICC profiles are dropped from the output. That is what you want for privacy-sensitive workflows and a problem if you need camera data downstream — keep the original file if you do.

Gmail caps outgoing attachments at 25 MB (it switches to a Drive link above that). Other providers differ — Outlook.com and many corporate mail servers sit lower, and some gateways count the base64-encoded size, which is about a third larger than the file on disk. Compress with headroom under whatever your recipient's server allows rather than assuming a single universal number.