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",
    "colorMode": "rgb",
    "outlineText": false,
    "imageFormat": "auto",
    "imageQuality": 85,
    "maxImageDpi": 300
  }
}

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",
    "type": "url",
    "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"
  }
}

Page Size#

With no dpi and a scale of 1, each PDF page is the size of your canvas, at 96 px per inch. A 794×1123 canvas gives an A4 page and 816×1056 gives US Letter.

The a4-document (2480×3508) and us-letter (2550×3300) size presets are 300 dpi pixel sizes for images. A PDF rendered at them comes out about 3 times larger than the paper size.

DPI (Resolution)#

dpi scales the PDF page. The page is multiplied by dpi / 72.

{
  "pdfOptions": {
    "dpi": 150
  }
}

Leave dpi unset when you want a real paper size such as A4 or Letter. Text and shapes stay sharp at any size. To get higher-resolution photos, use larger source images.

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

Outline Text#

Some print shops reject PDFs that contain certain fonts, often with an error about unnamed or Type 3 fonts, and ask for text "converted to outlines". Set outlineText to true to do exactly that:

{
  "pdfOptions": {
    "colorMode": "cmyk",
    "outlineText": true
  }
}

Every piece of text is drawn as a vector shape instead of letters in a font, so the PDF contains no fonts at all. Text looks the same and stays sharp at any zoom or print size.

It works with or without colorMode: "cmyk" and with imageFormat, in the same processing step. Links and the document title are kept.

On its own (without colorMode: "cmyk" or imageFormat: "jpeg"), outlining keeps every image lossless, so a photo-heavy RGB PDF can come out several times larger. Add "imageFormat": "jpeg" if file size matters.

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#

To pick pages from a multi-page template, use response.includePages. By default every page is included.

{
  "response": {
    "format": "pdf",
    "type": "url",
    "includePages": [2, 3, 4]
  }
}

This generates a PDF with only pages 2, 3 and 4 from your template. You are billed only for the pages you render.

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",
      colorMode: "cmyk",
      outlineText: true,
    },
  }),
});

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.