PDF Options

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",
    "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 using any CSS margin value:

{
  "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 takes any CSS length and overrides the global margin for that side — 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

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",
    },
  }),
});

Combining with Scale#

Use response.scale alongside pdfOptions for even higher resolution output:

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

This produces a PDF at 2x the template dimensions with 300 DPI — ideal for large-format printing.