Reduce PDF File Size: What Compression Can Actually Change

PDF compression depends on what occupies the file. A document with inefficient object structure may shrink after a lossless rewrite. A scan dominated by an already-compressed image may barely change, or even become slightly larger.

We tested RelayPDF's basic POST /v1/pdf/compress operation on three synthetic inputs. The operation is a lossless rewrite with object streams; it does not downsample page images. Download the example projects, fixtures, and results.

Identify the expensive content first

A PDF contains page instructions, fonts, images, metadata, and other objects. “Ten pages” is not enough information to predict size. Ten pages of text can be smaller than one detailed scan.

Start by checking whether the file is mostly text, scanned images, or exported photographs. Look at image dimensions and whether your source workflow embeds unnecessarily large assets. Improving the HTML's source images may be more effective than trying to shrink the finished PDF.

Also identify document features you need to preserve. A visually unchanged rewrite is not automatically a preservation guarantee for signatures, attachments, forms, or specialized metadata. Use ordinary unsigned documents for this tutorial and validate the properties that matter in your application.

Run the basic compression request

After installing the Python requirements and loading the environment created by npx @relaypdf/cli setup --env .env, use:

import base64
from pathlib import Path
from api import request, atomic_write

source = Path("fixtures/report-unoptimized.pdf").read_bytes()
response = request("POST", "/v1/pdf/compress", {
    "file": base64.b64encode(source).decode(),
    "response": "binary"
})
compressed = response.content
if not compressed.startswith(b"%PDF-"):
    raise ValueError("Expected PDF bytes")
atomic_write("work/compressed.pdf", compressed)
print(len(source), len(compressed))

The basic operation differs from /v1/pdf/compress-advanced. Do not copy advanced image-quality options into the basic request and expect them to take effect. Consult the operation's reference before selecting a lossy transformation.

Results on three fixtures

These measurements were recorded against the staging API on September 7, 2026. Each input was processed once. Sizes are bytes, not rounded megabytes.

A negative reduction means the output grew. The text fixture was intentionally saved without object streams, giving the rewrite an opportunity to improve its structure. The scan and noisy-image fixture already contained compressed image data.

The noise image is a reproducible image-heavy test case, not a representative photograph collection. These three files demonstrate different outcomes; they do not establish an average compression ratio for customer documents.

Download the text input and compressed text output, or compare the scan input with its compressed output. All measured sizes are in the results JSON.

Validate before choosing which file to keep

Check that page counts and dimensions match. Extract text from both documents when text is present. Rasterize both at the same resolution and compare pages for clipping, rotation, or missing content.

Our accompanying validation compares rendered pages for all three pairs. The PDF regression tutorial explains the combination of structural, text, and visual checks. Do not compare PDF bytes directly: metadata and object ordering can change without changing the document's appearance.

For a pipeline whose only objective is a smaller download, keep the original when the output is larger and both files otherwise satisfy the same requirements. Do not replace the source solely because the API call succeeded.

When image changes are necessary

Lossless document restructuring cannot guarantee a large reduction in an image-heavy file. If you can accept reduced image fidelity, consider downsampling or changing image compression through an operation that explicitly supports it. Decide the smallest text and graphics that must remain readable before selecting quality settings.

QPDF's file-size guidance describes the distinction between document optimization and image resampling. The same distinction is useful when evaluating API claims: ask what the operation changes and what it preserves.

For documents generated from HTML, size source images for their printed dimensions, reuse assets, and avoid embedding unnecessary font families. If you need an attachment-size ceiling, validate the final byte count and provide a clear fallback when the ceiling cannot be reached without unacceptable loss.

See the PDF tools overview and OpenAPI reference for RelayPDF's supported inputs. For the generation side of the pipeline, use HTML-to-PDF.