Image & Video APIs
Menu

Optimize PDFs

Last updated: Apr-30-2025

Whether you're delivering PDFs from your website, or using Cloudinary to store and share them, PDF compression may be of interest to you. By compressing PDFs, especially if they're image rich, you can benefit from big storage savings and faster download speeds.

Important
PDF optimization is currently available to certain customers only. If you'd like to enable it for your product environment, please contact support.

On this page:

Rate this page:

Automatic quality for PDFs

You can optimize the size of your PDFs automatically:

In each case, use the automatic quality transformation (q_auto in URLs), which applies a certain amount of compression to your PDFs, while maintaining visual quality.

Notes
  • Quality types such as best, good, eco etc. aren't yet supported when applying automatic quality to PDFs.
  • Cloudinary doesn't optimize PDFs that exceed 10 pages or 5 MB in size—it returns the original instead.
  • Some PDFs, even below these limits, can't be optimized and reduced in size. In these cases, Cloudinary returns the original.
  • PDFs with images typically benefit from better optimization than those without.
  • PDF optimization is intended mainly for on-screen viewing (in a browser or PDF viewer). For high-quality printing, it's best to avoid optimizing the PDF.
  • There's a special transformation count for applying automatic quality to PDFs.

Optimize PDFs on delivery

Important
To reduce the chances of malware or other potentially harmful files being distributed via the Cloudinary domain, PDFs (and certain other file formats) are blocked for delivery by default for FREE accounts. To deliver PDFs, make sure the Allow delivery of PDF and ZIP files option is selected in the Security page of the Console Settings.

If you're storing your original uncompressed PDFs in your Cloudinary product environment, you can deliver compressed PDFs on the fly to your end users without affecting the original copy.

To deliver optimized PDFs, apply the q_auto transformation parameter to your delivery URL, either directly, or using one of our SDKs, as shown:

https://res.cloudinary.com/cld-docs/image/upload/q_auto/39_Acacia_Road_Brochure.pdf
Open In Transformation Builder

In this case, the original PDF is 1.8 MB and the optimized PDF is 1.1 MB.

Optimize PDFs on upload

If you want to save on storage, you can optimize PDFs on upload using an incoming transformation. In this case, the compressed version of the PDF is stored in your product environment. 

curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=39_Acacia_Road_Brochure_incoming.pdf&transformation=q_auto&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

Response:

JSON
{
  "asset_id": "a5f6b530d5047595ecc6eb9749b964e2",
  "public_id": "39_Acacia_Road_Brochure_incoming",
  "version": 1743089313,
  "version_id": "a7fda692479094917db557c39377236d",
  "signature": "c1b5400f382ebdbabff00e85d7218eda8b10dca9",
  "width": 595,
  "height": 841,
  "format": "pdf",
  "resource_type": "image",
  "created_at": "2025-03-27T15:28:33Z",
  "tags": [],
  "pages": 4,
  "bytes": 1115921,
  "type": "upload",
  "etag": "8efd8251bf8ee5993f4cac036d4265f8",
  "placeholder": false,
  "url": "http://res.cloudinary.com/cld-docs/image/upload/v1743089313/39_Acacia_Road_Brochure_incoming.pdf",
  "secure_url": "https://res.cloudinary.com/cld-docs/image/upload/v1743089313/39_Acacia_Road_Brochure_incoming.pdf",
  "asset_folder": "",
  "display_name": "39_Acacia_Road_Brochure_incoming",
  "metadata": {
    "my_metadata": [
      "value1",
      "value2"
    ]
  },
  "original_filename": "39_Acacia_Road_Brochure_incoming",
  "api_key": "614335564976464"
}

Optimize previously uploaded PDFs

If you've got original, uncompressed PDFs already in your Cloudinary product environment, and you want to save some storage, you can follow these steps to overwrite an original PDF with an optimized PDF:

  1. Use the original PDF's URL as the upload source.
  2. Apply the automatic quality transformation as an incoming transformation.
  3. Set the public ID to match the existing PDF.
  4. Include the overwrite and invalidate parameters.

For example:

curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST \
--data 'file=https://res.cloudinary.com/cld-docs/image/upload/39_Acacia_Road_Brochure_original.pdf&public_id=39_Acacia_Road_Brochure_original&overwrite=true&invalidate=true&transformation=q_auto&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

This applies the automatic quality transformation, overwrites the existing asset, and invalidates any cached versions on the CDN.

Related topics

✔️ Feedback sent!