Compress PDF via API: Reduce File Size Programmatically

February 24, 2026 · 7 min read

Milena Szymanowska

PDFBolt Co-Founder

Compress PDF via API with multiple compression levels

PDFs generated from HTML or web pages with images can get large. A product catalog with high‑resolution photos might produce a 15 MB file. An annual report with charts and screenshots could hit 8 MB. These sizes cause real problems: slow downloads, email attachment limits, expensive storage, and poor user experience. Manual compression through Acrobat or online tools doesn't work when you're generating hundreds of PDFs programmatically. You need compression that runs as part of your generation pipeline – and with a PDF compression API, you can apply it in the same request that creates the PDF.

Why Compress PDFs Programmatically

If you generate PDFs via an API, compression needs to happen automatically during generation.

Common scenarios where PDF compression matters:

Email attachments. Many email providers cap attachments at 10-25 MB. A product catalog or image-heavy report needs to stay under that limit.
Web downloads. Users on mobile connections won't wait for a 20 MB PDF. Smaller files mean faster downloads and lower bounce rates on your download pages.
Storage costs. If you store generated PDFs in S3 or similar storage, file size directly affects your monthly bill. Compressing a 10 MB file to 3 MB cuts storage costs by 70%.
API response time. Smaller PDFs transfer faster over the network. Compression adds some processing time on the server, but the smaller file size usually makes up for it during download – especially on slower connections.

PDF Compression Levels

PDFBolt offers four compression levels through a single API parameter. Each level represents a different tradeoff between file size and image quality.

Lossless

{ "compression": "lossless" }

Lossless compression reduces file size without any quality loss. It works by:

Downscaling images to their rendered display size (at 2x resolution for print quality)
De-duplicating identical images that appear multiple times in the document

This is the right choice when image quality cannot be compromised at all. File size reductions are typically 10-40% for image-heavy documents, less for text-only content.

Low

{ "compression": "low" }

Low compression applies light JPEG quality reduction to images. The visual difference is imperceptible in most cases. File size reductions are typically 30-55% for image-heavy PDFs.

Best for: documents where quality matters but some compression is acceptable (client-facing reports, branded materials).

Medium

{ "compression": "medium" }

Medium compression balances quality and file size. Images have visible quality reduction at 200%+ zoom but look fine at normal viewing sizes. File size reductions of 45-70% are common.

Best for: internal documents, email attachments, web downloads where file size matters more than print quality.

High

{ "compression": "high" }

High compression produces the smallest files. Image quality is noticeably reduced at 100% zoom. Text remains sharp (compression only affects raster images, not vector content or fonts). File size reductions of 60-90% are typical for image-heavy PDFs.

Best for: archival storage, bandwidth-constrained environments, documents that will be viewed briefly on mobile screens.

Text-only PDFs

Compression is most effective on image-heavy PDFs. If your document is mostly text with few or no images, the file is already small and compression will have minimal impact. For tips on image and HTML optimization, see optimizing HTML for PDF.

Real-World Example: Product Catalog

To test compression in practice, we prepared a 10-page HTML furniture catalog with high‑resolution product photos and converted it to PDF via the API (23.7 MB without compression). Here are the results at each level:

Level	File size	Reduction	View
No compression	23.7 MB	–	–
Lossless	10.3 MB	56%	View PDF
Low	2.8 MB	88%	View PDF
Medium	1.9 MB	92%	View PDF
High	1.6 MB	93%	View PDF

Results vary by content. This catalog contains many high‑resolution product photos, which is a best-case scenario for compression. Text-heavy documents will see smaller reductions.

Code Examples

Add the compression parameter to your HTML to PDF or URL to PDF API request. Here are working examples in Node.js, Python, and cURL.

Node.js

const fs = require('fs');

async function generateCompressedPdf() {
    const response = await fetch('https://api.pdfbolt.com/v1/direct', {
        method: 'POST',
        headers: {
            'API-KEY': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            url: 'https://your-site.com/catalog',
            printBackground: true,
            compression: 'medium'
        })
    });

    if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP ${response.status} - ${errorText}`);
    }

    const pdfBuffer = await response.arrayBuffer();
    fs.writeFileSync('catalog-compressed.pdf', Buffer.from(pdfBuffer));
    console.log('PDF generated successfully');
}

generateCompressedPdf().catch(console.error);

Python example

import requests
import json

url = "https://api.pdfbolt.com/v1/direct"
headers = {
    "API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data_json = '''{
    "url": "https://your-site.com/report",
    "printBackground": true,
    "compression": "low"
}'''

data = json.loads(data_json)

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()

    with open("report-compressed.pdf", "wb") as f:
        f.write(response.content)
    print("PDF saved as report-compressed.pdf")

except requests.exceptions.HTTPError as e:
    print(f"HTTP {response.status_code}")
    print(f"Error Message: {response.text}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

cURL example

curl 'https://api.pdfbolt.com/v1/direct' \
  -H 'Content-Type: application/json' \
  -H 'API-KEY: YOUR_API_KEY' \
  -d '{
    "url": "https://your-site.com/invoice",
    "printBackground": true,
    "compression": "lossless"
  }' \
  -o invoice.pdf

Test different compression levels in the Playground to see the quality vs size tradeoff on your specific content.

More Languages

For examples in Java, PHP, C#, Ruby, and Go, see the quick start guide.

Combining Compression with Other Features

Compression works alongside other PDFBolt parameters. Common combinations:

Compression + Templates

{
  "templateId": "your-template-id",
  "templateData": { "...": "..." },
  "compression": "medium"
}

Generate PDFs from Handlebars templates with compression applied to the output. Useful for templates that include logos and charts. For a guide on creating reusable templates, see Reusable Layouts for PDF Generation.

Compression + Print Production

{
  "url": "https://your-site.com/brochure",
  "printBackground": true,
  "compression": "lossless",
  "printProduction": {
    "pdfStandard": "pdf-x-4",
    "colorSpace": "cmyk",
    "iccProfile": "fogra51"
  }
}

Generate print-ready PDFs with CMYK color conversion and lossless compression. For print output, avoid medium or high compression since image quality matters on paper.

Compression + Async Processing

{
  "url": "https://your-site.com/catalog",
  "compression": "medium",
  "webhook": "https://your-api.com/pdf-ready"
}

Send to the async endpoint for batch processing. Generate hundreds of compressed PDFs without blocking your application, ideal for automated workflows. Results arrive via webhook.

Choosing the Right Compression Level

Priority	Recommended level	Typical reduction
No quality loss, some size reduction	`lossless`	10-40%
Best quality with meaningful compression	`low`	30-55%
Balanced quality and size	`medium`	45-70%
Smallest file possible	`high`	60-90%
Print output (CMYK/PDF/X)	`lossless`	10-40%
Email attachments	`medium`	45-70%
Mobile downloads	`medium` or `high`	45-90%
Archival storage	`high`	60-90%

When in doubt, start with low. It produces files that are meaningfully smaller than uncompressed while keeping visual quality indistinguishable from the original at normal viewing sizes.

Frequently Asked Questions

How do I compress a PDF via API?

Add "compression": "medium" (or lossless, low, high) to your PDFBolt API request body. The compression is applied during PDF generation. No separate compression step is needed. See the compression parameter documentation for details.

Does compression affect text quality?

No. Compression only affects raster images (photos, screenshots, rendered charts). Text, vector graphics, and fonts remain sharp at all compression levels. If your PDF is text-only, compression will have minimal impact on file size.

What is lossless PDF compression?

Lossless compression reduces file size without any quality loss. It works by downscaling images to their rendered display size (at 2x resolution) and de-duplicating identical images. You get a smaller file with no visible difference from the original.

Can I compress existing PDFs?

PDFBolt's compression applies during PDF generation, not to existing files. For compressing arbitrary existing PDFs, tools like Ghostscript or iLovePDF handle that use case.

How much can PDF compression reduce file size?

Reductions depend on the content. Image-heavy PDFs (catalogs, reports with photos) see the most benefit: 10-90% reduction depending on the compression level. Text-heavy PDFs with few images see minimal reduction (5-15%) since text and fonts are already compact.

Can I combine compression with CMYK conversion?

Yes. Set both compression and printProduction parameters in the same request. For print output, use lossless compression to avoid quality loss. See the print production guide for more on CMYK and PDF/X settings.

Which compression level should I use for email attachments?

Use medium compression for email attachments. It typically reduces image-heavy PDFs by 45-70%, which is usually enough to stay under email attachment limits (10-25 MB). If the file is still too large, try high compression.

Conclusion

No extra tools, no post-processing. Add the compression parameter to your existing HTML to PDF API or URL to PDF API requests, and every generated PDF comes out smaller.

Four levels cover different tradeoffs – lossless for zero quality loss, low for near-invisible compression, medium for balanced quality and size, high for minimum file size. Try them on your own content in the Playground.

Finally, a diet plan that works. For your PDFs, at least. 📉

Why Compress PDFs Programmatically​

PDF Compression Levels​

Lossless​

Low​

Medium​

High​

Real-World Example: Product Catalog​

Code Examples​

Node.js​

Combining Compression with Other Features​

Compression + Templates​

Compression + Print Production​

Compression + Async Processing​

Choosing the Right Compression Level​

Frequently Asked Questions​

Conclusion​