Compress PDFs

Basic request

Send the PDF as the body of POST /v1/compress. The one option is pdf.quality, which picks a preset. Without it the preset is medium.

curl -X POST "https://api.smolmac.com/v1/compress?pdf.quality=small" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @report.pdf \
  -o report.min.pdf

import { readFile, writeFile } from "node:fs/promises";

const response = await fetch("https://api.smolmac.com/v1/compress?pdf.quality=small", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMOL_API_KEY}` },
  body: await readFile("report.pdf"),
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

await writeFile("report.min.pdf", Buffer.from(await response.arrayBuffer()));

const result = JSON.parse(response.headers.get("smol-result"));
console.log(result.pages, "pages,", result.savings_percent, "% smaller");

import json, os, requests

with open("report.pdf", "rb") as f:
    response = requests.post(
        "https://api.smolmac.com/v1/compress",
        params={"pdf.quality": "small"},
        headers={"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"},
        data=f,
    )
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")

with open("report.min.pdf", "wb") as out:
    out.write(response.content)

result = json.loads(response.headers["smol-result"])
print(result["pages"], "pages,", result["savings_percent"], "% smaller")

The response body is the compressed PDF. The Smol-Result header includes the page count, which is what the price is based on:

{
  "kind": "pdf",
  "input_format": "pdf",
  "output_format": "pdf",
  "original_size": 8412630,
  "output_size": 1935211,
  "savings_percent": 77.0,
  "kept_original": false,
  "increased": false,
  "width": null,
  "height": null,
  "pages": 48,
  "duration_seconds": null,
  "video_codec": null,
  "warnings": []
}

The five presets

Most of the bytes in a large PDF are images: scans, photos, screenshots. A preset sets two things for those images: the longest side they may have, in pixels, and the JPEG quality they are saved at.

These are the presets of the Smol Mac app, with the same numbers. original is a preset name, not a promise to leave images alone: images with a side longer than 2400 pixels are still scaled down.

What changes in the file

• Each image inside the PDF is scaled down to the limit of the preset, if it is larger, and recompressed with the MozJPEG encoder at the quality of the preset.
• Small images are left alone: images under 10,000 pixels and JPEGs under 8,192 bytes. There is nothing to gain from them.
• An image is replaced only if the new version is smaller. Otherwise the existing one stays.
• The file structure is then rewritten: streams are compressed, objects are packed, and the file is linearised so a viewer can show the first page before the whole file has arrived.

Text, vector graphics and fonts are not re-encoded. A PDF that is mostly text has little to give, and the saving comes from the structure rewrite alone.

If some images could not be recompressed, the request still succeeds and the result carries a warning:

"warnings": [
  "Some images inside the PDF could not be recompressed and were left as they were."
]

If the compressed file is not smaller than the input, the API tries a rewrite of the structure only, which loses nothing. If that is not smaller either, you get the input back with Smol-Kept-Original: true and the request is free. See Kept original.

Password-protected PDFs

A PDF that needs a password to open is refused. The API has no way to take a password, and it does not try to remove one.

{
  "error": {
    "type": "processing_error",
    "code": "encrypted_pdf",
    "message": "This PDF is password protected. Remove the password and try again.",
    "param": null,
    "request_id": "req_Vt5Hc0PqL8wZr3NmK1xD",
    "doc_url": "https://smolmac.com/docs/reference/errors#encrypted_pdf"
  }
}

Remove the password with the software that set it, then send the file again. The request is not billed, and retrying the same file gives the same error. The same rule applies when a PDF is converted to an image or has its metadata removed.

Page limits

The number of pages a PDF may have depends on the plan of the account:

A PDF with more pages fails with 422 limit_exceeded, and the message states the page count and the limit. The request is not billed. To process a longer document, split it into parts first. The other limits are in Limits.

Billing

PDF compression costs $0.04 per started 100 pages. The page count is the one in the result object.

The price does not depend on the preset or on the size of the file. Failed requests and requests where the original was kept are free. Smol-Billed tells you whether a request was charged. See Billing.

PDFs over 25 MB

A direct request takes a file of up to 25 MB and must finish within two minutes. For a larger PDF, upload it and create a job. The options are the same, sent as JSON:

curl -X POST "https://api.smolmac.com/v1/jobs" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "compress",
    "input": { "upload": "upl_Zk3Vb9QeT1mXc7HsW0yN" },
    "options": { "pdf": { "quality": "small" } }
  }'

Large files and jobs walks through the upload, the job and the download.