What PDF options can I control?

The pdfOptions object gives you control over the quality and formatting of your PDF output. These options only apply when response.format is set to "pdf".

All Options#

{
  "pdfOptions": {
    "title": "Spring Sale Flyer",
    "margin": "20px",
    "dpi": 300,
    "colorMode": "rgb",
    "imageFormat": "auto",
    "imageQuality": 85,
    "maxImageDpi": 300,
    "rangeFrom": 1,
    "rangeTo": 5
  }
}

Document Title#

Set the PDF's Title metadata. Browsers show it in the tab when the PDF is opened from a URL or stream, and PDF readers show it in the window title. Without it, viewers fall back to the file name or generic labels like "about:blank".

{
  "pdfOptions": {
    "title": "Spring Sale Flyer"
  }
}

If you don't set a title but pass response.fileName, the file name is used as the title automatically:

{
  "response": {
    "format": "pdf",
    "fileName": "invoice-1042"
  }
}

This PDF carries the title invoice-1042 even though pdfOptions.title was never set. Pass an explicit pdfOptions.title when you want the display title to differ from the file name.

Margins#

Add spacing around your PDF content. margin takes a pixel value such as "20px", or a plain number that is treated as pixels:

{
  "pdfOptions": {
    "margin": "20px"
  }
}

Useful for adding white space around the design when printing, or ensuring content doesn't get cut off at the edges.

{
  "pdfOptions": {
    "margin": "0px"
  }
}

Set to "0px" for edge-to-edge designs like posters or full-bleed prints.

Per-Side Margins#

Override individual sides with marginTop, marginBottom, marginLeft, and marginRight. Each overrides the global margin for that side, which is useful for asymmetric layouts like a footer disclaimer or a binding edge.

{
  "pdfOptions": {
    "margin": "20px",
    "marginBottom": "60px"
  }
}

DPI (Resolution)#

DPI controls the resolution of the PDF output.

Screen Quality#

{
  "pdfOptions": {
    "dpi": 72
  }
}

Best for PDFs viewed on screen — digital certificates, email attachments, online reports.

Print Quality#

{
  "pdfOptions": {
    "dpi": 300
  }
}

Best for physical printing — business cards, flyers, event badges, certificates that will be framed.

Color Mode#

Control the color space used in the PDF:

RGB (Default)#

{
  "pdfOptions": {
    "colorMode": "rgb"
  }
}

RGB is the standard for digital displays — monitors, phones, tablets. Use this for PDFs that will be viewed on screen.

CMYK#

{
  "pdfOptions": {
    "colorMode": "cmyk"
  }
}

CMYK is the standard for professional printing. Colors are converted to the Cyan, Magenta, Yellow, and Key (black) color space, ensuring accurate color reproduction on paper.

Use CMYK for:

• Business cards
• Brochures and flyers
• Magazine ads
• Any material sent to a print shop

Image Compression#

Photo-heavy PDFs can get large. The renderer stores any image it had to scale, crop, or composite as raw pixel data rather than reusing the original JPEG, so a print flyer with eight listing photos can easily run past 20 MB even when the source photos were a few hundred KB each.

Set imageFormat to "jpeg" to re-encode the embedded images:

{
  "pdfOptions": {
    "imageFormat": "jpeg",
    "imageQuality": 85,
    "maxImageDpi": 300
  }
}

On a real property flyer with eight listing photos, this took the output from 29.4 MB to 2.8 MB with no visible difference at print size. Reductions of 80 to 90% are typical for photo-heavy pages, and pages that are mostly text or vector shapes see little change.

What is safe#

• Text, shapes, and other vector content is not an image, so compression never touches it.
• Transparency is preserved exactly. A transparent image is stored as colour data plus a separate alpha mask, and only the colour data is re-encoded. The mask stays lossless, so logos and cut-out images keep clean edges.
• QR codes and barcodes are re-encoded like any other colour image, but they survive it. Across every quality setting down to 60, a 33x33-module code decoded with zero incorrect modules.

Where it is a poor fit#

JPEG is built for photographs. On images that are mostly flat colour with hard edges, such as screenshots, charts, diagrams, or logos flattened into the page as a raster, it produces visible ringing around the edges even at quality 85. Templates like that gain little from compression anyway, since that kind of image already compresses well losslessly. Leave imageFormat at "auto" for them, or raise imageQuality to 95 or above.

With CMYK#

colorMode: "cmyk" already recompresses images as part of the color conversion, so CMYK output is small before you touch imageFormat. Setting imageFormat: "jpeg" alongside it swaps that automatic behavior for the exact imageQuality you asked for. At the default of 85 that is often larger than CMYK on its own, and on graphics-heavy pages it can exceed the uncompressed render. Lower imageQuality if you want CMYK output smaller.

When to leave it off#

Compression rebuilds the document, which drops the tagged-PDF structure used by screen readers. colorMode: "cmyk" does the same. If accessibility tags matter for your output, leave both off. Text stays selectable, fonts stay embedded, links keep working, and page dimensions are unchanged either way.

Multi-page PDFs do not carry tags to begin with, so there is nothing extra to lose there.

Page Ranges#

For multi-page templates, control which pages appear in the final PDF:

All Pages (Default)#

{
  "pdfOptions": {
    "rangeFrom": null,
    "rangeTo": null
  }
}

Omit or set to null to include all pages.

Specific Range#

{
  "pdfOptions": {
    "rangeFrom": 2,
    "rangeTo": 4
  }
}

This generates a PDF containing only pages 2, 3, and 4 from your template.

Single Page#

{
  "pdfOptions": {
    "rangeFrom": 1,
    "rangeTo": 1
  }
}

Extract a single page from a multi-page template.

Complete Example#

Generate a print-ready certificate with full options:

const response = await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <YOUR_API_KEY>",
  },
  body: JSON.stringify({
    templateId: "<CERTIFICATE_TEMPLATE>",
    modifications: {
      name: "Sarah Chen",
      course: "UX Design Fundamentals",
      date: "March 25, 2026",
    },
    response: {
      format: "pdf",
      type: "url",
      scale: 1,
      fileName: "certificate-sarah-chen",
    },
    pdfOptions: {
      margin: "0px",
      dpi: 300,
      colorMode: "cmyk",
    },
  }),
});

DPI and Scale#

dpi and response.scale control the same thing, so they do not stack. When dpi is set on a PDF render it replaces response.scale entirely, using scale = dpi / 72.

{
  "response": {
    "format": "pdf",
    "type": "url",
    "scale": 2
  },
  "pdfOptions": {
    "dpi": 300
  }
}

The scale: 2 above is ignored. The render uses 300 / 72, or roughly 4.17x. To scale by an exact factor, set response.scale and leave dpi unset.