Imgix APIsRendering APIPDF

PDF

Options for rendering PDFs and other multi-page file formats (such as Adobe Illustrator files), and for producing PDFs as output. For an in-depth tutorial, see Managing Brand Assets from PDFs.

PDF Rendering Behavior

Any parameter — default parameters included — causes a PDF to go through the renderer. When that happens, Imgix rasterizes the file and serves a single page from it. Use page to choose which.

To serve a PDF in its original form with all its pages, either request it with no Imgix parameters, or use fm=pdf or rasterize-bypass. The download parameter also delivers the full, unmodified file.

PDF Complexity Affects Render Time

While PDFs made up mostly of images and text render efficiently, PDFs with a high volume of internal constructs — such as extensive path construction or numerous overlapping transparency layers — may require additional time to render and can time out when a transformation (such as resizing or cropping) is applied. If you’re experiencing a PDF that renders unexpectedly slowly, contact us so we can take a closer look.

Producing a PDF as output

fm=pdf returns the result as application/pdf. What it does depends on the source.

An image source is rendered as usual and delivered as a one-page PDF. Every parameter applies, exactly as for any other output format. Opaque images are embedded as JPEG — so q, auto=compress and jpg-progressive all apply, and the PDF adds only a few hundred bytes over the JPEG. Images with transparency are embedded losslessly, with the alpha channel kept as a soft mask. The output colour profile set by cs is embedded; the image is never converted to CMYK. An animated source contributes a single frame — the first, or the one chosen with frame — since a PDF produced this way never has more than one page.

A PDF source with a bare fm=pdf, or with only sizing and filter parameters, returns the original file byte for byte and ignores those parameters. Adding auto=compress, q or dpi optimizes it instead, and page extracts a single page.

An EPS source returns its vector PDF conversion, staying vector; sizing, filter and page parameters are ignored, while auto=compress, q and dpi optimize the converted PDF. If the vector conversion fails, the EPS is rasterized and every image parameter applies.

Optimization and page extraction require the exact lowercase fm=pdf. On a PDF source, fm=PDF always returns the original file, even with page.

Optimizing a PDF

A PDF source is optimized when fm=pdf is combined with any of:

ParameterEffect
auto=compressRecompresses images at quality 45 (unless q is set), capped at 150 pixels per inch. auto may list several values, so auto=format,compress counts.
q=1–100Recompresses images at this JPEG quality. Values outside the range are clamped. Without q or auto=compress, the quality is 75.
dpi=<n>Caps images at n pixels per inch.

A source default of auto=compress will optimize a bare fm=pdf

Optimization is triggered by auto=compress being present, including when it comes from the source’s default parameters rather than the URL. On such a source, what looks like a bare fm=pdf is not bare, and the PDF is optimized rather than returned byte for byte. If you need the original file, make sure auto=compress is not applied.

Only images are changed. Text, fonts, vector graphics, links, annotations, forms and bookmarks are carried over as they are, and page content is never rewritten. The file is also repacked more compactly and unused resources are dropped, which can shrink it even when no image changes. Images are never enlarged: if a recompressed image is not smaller than the original, the original is kept.

Which images are recompressed

Only 8-bit images in DeviceGray, DeviceRGB, DeviceCMYK or an ICC profile with 1, 3 or 4 components are recompressed, and then only with a single JPEG (DCT), Flate or JPEG 2000 filter, no /Decode array (CMYK excepted), no colour-key mask, no explicit JPEG colour transform, and no more than 100 megapixels. JPEG 2000 images additionally must have 1 or 3 components and no embedded alpha.

Everything else is left untouched — palette (Indexed), CalGray, CalRGB, Lab, Separation and DeviceN images; 1-, 2-, 4- and 16-bit images typical of scans; images using LZW, RunLength or chained filters; and inline images. CMYK images stay CMYK and are never converted to RGB.

When the original file is returned instead

Optimizing a whole document returns the source unchanged when the PDF is encrypted, digitally signed (including preflight signatures such as Enfocus Certified PDF), damaged or malformed, has more than 300 pages, is larger than 200 MB, holds more than 1,000,000 objects, has page content larger than 256 MiB once decompressed, or carries more than 200 megapixels of images to recompress. The same is true when the optimized version would not be smaller than the original.

These limits apply to whole-document optimization only — see page for extraction, which has its own rules and returns a 422 rather than the original file when it cannot proceed.

Content credentials (C2PA)

A PDF response is signed only when the request asks for provenance with provenance=c2pa and the source already carries Content Credentials. A source without them is never signed.

Whenever a PDF is optimized or extracted, any Content Credentials manifest embedded in the source is removed from the output, even when signing was not requested, because it cannot remain valid for the new bytes. A response that is the original file unchanged is never re-signed — it is the source, and keeps whatever credentials it already had.

Not supported

Combining several images into one PDF, CMYK output for image sources, page ranges (page takes a single page), linearization (“fast web view”), and margin or bg as layout options. To lay an image out on the page, use pad with bg.