HTML Renderer

Convert HTML content to PDF or image with full CSS support.

Endpoint

POST /api/v1/renderer/html

Description

The HTML Renderer converts any HTML content to PDF or image format. It supports full CSS styling, custom fonts, and responsive layouts.

Request Body

{
  "html": "<html><body><h1>Hello World</h1></body></html>",
  "options": {
    "format": "A4",
    "orientation": "portrait"
  }
}

Query Parameters

POST /api/v1/renderer/html?format=pdf&response=binary&pageFormat=A4&orientation=landscape

Parameter	Type	Default	Description
`format`	string	`pdf`	Output format: `pdf`, `png`, `jpg`
`response`	string	`binary`	Response type: `binary`, `base64`
`pageFormat`	string	`A4`	Page size: `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	string	`portrait`	Page orientation: `portrait`, `landscape`
`margins`	string	-	Page margins (e.g., `"20mm"` or `"10mm 20mm 10mm 20mm"`)
`scale`	number	`1`	Scale factor (0.1-2)
`printBackground`	boolean	`true`	Include background in output
`displayHeaderFooter`	boolean	`false`	Show header/footer
`headerTemplate`	string	-	Custom header HTML
`footerTemplate`	string	-	Custom footer HTML
`timeout`	number	`30000`	Render timeout in ms (1000-120000)
`width`	string	-	Custom page width
`height`	string	-	Custom page height
`pageRanges`	string	-	Page ranges to print (e.g., `"1-5, 8"`)
`imageType`	string	`png`	Image type for non-PDF: `png`, `jpeg`, `jpg`
`quality`	number	`90`	Image quality for JPEG (1-100)
`fullPage`	boolean	`true`	Capture full page height
`omitBackground`	boolean	`false`	Transparent background

Options Object

PDF Options

{
  "html": "<h1>Hello</h1>",
  "options": {
    "format": "A4",
    "orientation": "portrait",
    "margins": {
      "top": "20mm",
      "right": "20mm",
      "bottom": "20mm",
      "left": "20mm"
    },
    "scale": 1,
    "printBackground": true,
    "displayHeaderFooter": true,
    "headerTemplate": "<div style='font-size:10px; text-align:center; width:100%'>Company Name</div>",
    "footerTemplate": "<div style='font-size:10px; text-align:center; width:100%'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    "timeout": 30000,
    "pageRanges": "1-3"
  }
}

Image Options

{
  "html": "<h1>Hello</h1>",
  "options": {
    "imageType": "png",
    "quality": 90,
    "fullPage": true,
    "omitBackground": false
  }
}

Format vs PageFormat

Query param format refers to output format (pdf, png, jpg)
Body option format refers to page size (A4, Letter, etc.)

Use pageFormat query param to set page size via URL.

Options Reference

format (body) / pageFormat (query)

Page size for PDF output.

Value	Dimensions
`A4`	210mm × 297mm (default)
`A3`	297mm × 420mm
`A5`	148mm × 210mm
`Letter`	8.5" × 11"
`Legal`	8.5" × 14"
`Tabloid`	11" × 17"

orientation

Page orientation for PDF output.

Value	Description
`portrait`	Vertical orientation (default)
`landscape`	Horizontal orientation

margins

Page margins. Can be specified as:

Single value: "20mm" (all sides)
Two values: "10mm 20mm" (top/bottom, left/right)
Four values: "10mm 20mm 10mm 20mm" (top, right, bottom, left)
Object: { "top": "10mm", "right": "20mm", "bottom": "10mm", "left": "20mm" }

scale

Scale factor for the content.

Range: 0.1 to 2
Default: 1

printBackground

When true, includes CSS backgrounds and background images in the output.

displayHeaderFooter

When true, displays custom header and footer templates.

headerTemplate / footerTemplate

Custom HTML templates for headers and footers. Available classes:

.date - Current date
.title - Document title
.url - Document URL
.pageNumber - Current page number
.totalPages - Total page count

Example:

<div style="font-size: 10px; width: 100%; text-align: center;">
  Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>

timeout

Maximum time to wait for rendering in milliseconds.

Range: 1000 to 120000
Default: 30000

width / height

Custom page dimensions. Overrides format when specified.

Examples: "800px", "21cm", "8.5in"

pageRanges

Specific pages to include in the output.

Examples: "1-5", "1, 3, 5", "1-3, 5-8"

imageType

Image format when output format is png or jpg.

Value	Description
`png`	PNG format (default)
`jpeg`	JPEG format
`jpg`	JPEG format (alias)

quality

JPEG compression quality.

Range: 1 to 100
Default: 90

fullPage

When true, captures the entire page content including content below the fold.

omitBackground

When true, renders with a transparent background (PNG only).

Examples

Basic PDF

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Invoice</h1><p>Thank you for your order!</p>"
  }' \
  --output invoice.pdf

Styled HTML Document

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><head><style>body { font-family: Arial; } h1 { color: #ea997e; } .container { padding: 40px; }</style></head><body><div class=\"container\"><h1>Welcome</h1><p>This is a styled document.</p></div></body></html>",
    "options": {
      "format": "A4",
      "printBackground": true
    }
  }' \
  --output styled.pdf

Landscape with Custom Margins

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html?format=pdf&pageFormat=A4&orientation=landscape" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Landscape Report</h1>",
    "options": {
      "margins": {
        "top": "25mm",
        "right": "25mm",
        "bottom": "25mm",
        "left": "25mm"
      }
    }
  }' \
  --output report.pdf

PNG Screenshot

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html?format=png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"background: #ea997e; padding: 50px; color: white;\"><h1>Social Card</h1></div>",
    "options": {
      "fullPage": true,
      "printBackground": true
    }
  }' \
  --output social-card.png

With Header and Footer

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Report</h1><p>Content goes here...</p>",
    "options": {
      "displayHeaderFooter": true,
      "headerTemplate": "<div style=\"font-size:10px; width:100%; text-align:center; margin-top:10px;\">CONFIDENTIAL</div>",
      "footerTemplate": "<div style=\"font-size:10px; width:100%; text-align:center;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
      "margins": {
        "top": "40mm",
        "bottom": "30mm"
      }
    }
  }' \
  --output report.pdf

Response

Success (Binary)

Status: 200 OK
Content-Type: application/pdf, image/png, or image/jpeg
Body: Raw binary data

Success (Base64)

{
  "data": "<base64-encoded-content>",
  "contentType": "application/pdf"
}

Error Response

{
  "error": "Bad Request",
  "message": "HTML content is required",
  "statusCode": 400
}

Endpoint​

Description​

Request Body​

Query Parameters​

Options Object​

PDF Options​

Image Options​

Options Reference​

format (body) / pageFormat (query)​

orientation​

margins​

scale​

printBackground​

displayHeaderFooter​

headerTemplate / footerTemplate​

timeout​

width / height​

pageRanges​

imageType​

quality​

fullPage​

omitBackground​

Examples​

Basic PDF​

Styled HTML Document​

Landscape with Custom Margins​

PNG Screenshot​

With Header and Footer​

Response​

Success (Binary)​

Success (Base64)​

Error Response​