Conversion Parameters

Our API offers parameters for customizing HTML to PDF conversion. This section details each parameter, with examples, to help you tailor the output to your needs.

Input Parameters

html

Type: string

Required: No (mandatory only if url is not provided)

Details: Accepts Base64-encoded HTML content, allowing you to provide the HTML directly for generating a PDF.

Usage:

{
  "html": "PGh0bWw+Cjxib2R5Pgo8cD5UZXN0IHBhcmFncmFwaDwvcD4KPC9ib2R5Pgo8L2h0bWw+Cg=="
}

This example generates a PDF containing the text: “Test paragraph”.

tip

Ensure your HTML content is properly encoded in Base64 format before passing it to this parameter. You can use online tools or libraries to perform the conversion.

url

Type: string

Required: No (mandatory only if html is not provided)

Details: Accepts any valid URL. This allows specifying the webpage to be converted to a PDF.

Usage:

{
  "url": "https://example.com"
}

Page Parameters

emulateMediaType

Type: string

Required: No

Default Value: print

Details: Determines the media type for rendering the PDF.

Allowed Values:

Value	Description
`screen`	Generates a PDF using styles optimized for digital screens.
`print`	Generates a PDF using styles intended for print.

Usage:

{
  "url": "https://example.com",
  "emulateMediaType": "screen"
}

javaScriptEnabled

Type: boolean

Required: No

Default Value: true

Details: Determines whether JavaScript execution is enabled on the source page during PDF generation.

Value	Description
`true`	Enables JavaScript execution. Dynamic content, animations, and interactive elements are rendered accurately.
`false`	Disables JavaScript execution. Improves performance and reduces rendering time, but dynamic or interactive content may not render correctly.

Usage:

{
  "url": "https://example.com",
  "javaScriptEnabled": true
}

httpCredentials

Type: object

Required: No

Details: Enables HTTP Basic Authentication by providing a username and password, allowing access to resources protected by authentication.

Property Name	Type	Description
`username`	`string`	The username for authentication. `required`
`password`	`string`	The password for authentication. `required`

Usage:

{
  "url": "https://example.com",
  "httpCredentials": {
    "username": "john",
    "password": "pa55w0rd"
  }
}

viewportSize

Type: object

Required: No

Details: Defines the viewport dimensions for the page, specifying the width and height in pixels. Both width and height must be included in the viewportSize object and must be integers.

Property Name	Type	Description
`width`	`number`	Width of the viewport in pixels. `required`
`height`	`number`	Height of the viewport in pixels. `required`

Usage:

{
  "url": "https://example.com",
  "viewportSize": {
    "width": 1280,
    "height": 800
  }
}

isMobile

Type: boolean

Required: No

Default Value: false

Details: Enables or disables mobile device emulation, affecting how the page is rendered and interacted with.

Value	Description
`true`	Simulates a mobile device by respecting the meta viewport tag and enabling touch events.
`false`	Disables mobile emulation, rendering the page as it would appear on a desktop device.

Usage:

{
  "url": "https://example.com",
  "isMobile": true
}

deviceScaleFactor

Type: number

Required: No

Default Value: 1

Details: Defines the level of scaling applied to the webpage during rendering. A higher scale factor enhances the resolution, making text and images appear sharper in the generated PDF. The allowed values range from 1 to 4.

Usage:

{
  "url": "https://example.com",
  "deviceScaleFactor": 2
}

note

Using a higher deviceScaleFactor can increase the file size and slightly prolong the processing time for generating the PDF.

extraHTTPHeaders

Type: object

Required: No

Details: Allows you to include additional custom HTTP headers in the request. You can specify up to 10 headers, but the order of the headers is not guaranteed.

Usage:

{
  "url": "https://example.com",
  "extraHTTPHeaders": {
    "X-extra-header": "test1",
    "X-extra-header2": "test2"
  }
}

cookies

Type: Array<Object>

Required: No

Details: Specifies a list of cookies to include in the request. Each cookie must include the name, value, and either an url or a combination of both domain and path to define its scope. Optional properties are available for further customization. A maximum of 10 cookies can be added.

Property Name	Type	Description
`name`	`string`	The name of the cookie. `required`
`value`	`string`	The value of the cookie. `required`
`url`	`string`	Specifies the URL for which the cookie is valid. `required` if `domain` and `path` are not used
`domain`	`string`	Specifies the domain for which the cookie is valid. `required` if `url` is not used
`path`	`string`	The URL path that must exist in the requested URL for the cookie to be sent. `required` with `domain`
`expires`	`number`	Expiration date of the cookie in UNIX timestamp format. `optional`
`httpOnly`	`boolean`	Indicates if the cookie is HTTP-only. `optional`
`secure`	`boolean`	Indicates if the cookie is secure. `optional`

Usage:

{
  "url": "https://example.com",
  "cookies": [
    {
      "name": "sessionId",
      "value": "abc123",
      "domain": "example.com",
      "path": "/"
    },
    {
      "name": "userPreferences",
      "value": "darkMode=true",
      "url": "https://example.com",
      "expires": 1739641833,
      "httpOnly": true,
      "secure": true
    }
  ]
}

waitUntil

Type: string

Required: No

Default Value: load

Details: Specifies the event that defines when the page is considered fully loaded during PDF generation. Select the value that best fits your page's content and loading behavior.

Allowed Values:

Value	Description
`domcontentloaded`	Completes when the `DOMContentLoaded` event fires, meaning the HTML document has been fully parsed.
`load`	Completes when the `load` event fires, ensuring all resources such as images and scripts are loaded.
`networkidle`	Completes when there are no active network requests for at least 500 ms, indicating the page is stable.
`commit`	Completes as soon as a network response is received, and the document begins loading.

Usage:

{
  "url": "https://example.com",
  "waitUntil": "networkidle"
}

waitForFunction

Type: string

Required: No

Details: Waits for a specified JavaScript function to execute and return true within the page’s context, ensuring that certain conditions are met before continuing.

Usage:

{
  "url": "https://example.com",
  "waitForFunction": "() => document.querySelector('.content-loaded') !== null"
}

waitForSelector

Type: object

Required: No

Details: Waits for a specified selector to satisfy a given state, such as appearing, disappearing, becoming visible, or hidden in the DOM.

Property Name	Type	Description
`selector`	`string`	CSS selector to target an element. `required`
`state`	`string`	State to wait for. Must be one of the allowed values. `required`

Allowed Values for state:

Value	Description
`attached`	Waits for the element to be present in the DOM.
`detached`	Waits for the element to not be present in the DOM.
`visible`	Waits for the element to have a non-empty bounding box and not have `visibility: hidden`. Elements with `display: none` are excluded.
`hidden`	Waits for the element to be either detached from the DOM, have an empty bounding box or `visibility: hidden`. Opposite of `visible`.

Usage:

{
  "url": "https://example.com",
  "waitForSelector": {
     "selector": "#removable-element",
     "state": "hidden"
    }
}

timeout

Type: number

Required: No

Default Value: 30000

Details: Defines the maximum time in milliseconds to wait for the page to load or for specific conditions to be met. Acceptable range is between 0 and 60000 (1 minute). If the timeout is exceeded, the request will fail with a timeout error.

Usage:

{
  "url": "https://example.com",
  "timeout": 40000
}

Pdf Layout

format

Type: string

Required: No

Default Value: Letter

Details: Specifies the paper format for the generated PDF. If both format and custom dimensions: width or height are provided, the format parameter takes priority.

Allowed Values:

Value	Size in Inches	Size in cm	Size in Feet
`Letter`	8.5in x 11in	21.6cm x 27.9cm	0.666ft x 0.917ft
`Legal`	8.5in x 14in	21.6cm x 35.6cm	0.666ft x 1.167ft
`Tabloid`	11in x 17in	27.9cm x 43.2cm	0.917ft x 1.417ft
`Ledger`	17in x 11in	43.2cm x 27.9cm	1.417ft x 0.917ft
`A0`	33.1in x 46.8in	84cm x 118.9cm	2.757ft x 3.898ft
`A1`	23.4in x 33.1in	59.4cm x 84cm	1.948ft x 2.757ft
`A2`	16.54in x 23.4in	42cm x 59.4cm	1.377ft x 1.948ft
`A3`	11.7in x 16.54in	29.7cm x 42cm	0.974ft x 1.377ft
`A4`	8.27in x 11.7in	21cm x 29.7cm	0.689ft x 0.974ft
`A5`	5.83in x 8.27in	14.8cm x 21cm	0.485ft x 0.689ft
`A6`	4.13in x 5.83in	10.5cm x 14.8cm	0.344ft x 0.485ft

Usage:

{
  "url": "https://example.com",
  "format": "A4"
}

landscape

Type: boolean

Required: No

Default Value: false

Details: Defines the orientation of the generated PDF.

Value	Description
`true`	Generates the PDF in landscape mode.
`false`	Generates the PDF in portrait mode (default).

Usage:

{
  "url": "https://example.com",
  "landscape": true
}

width

Type: string | number

Required: No

Details: Defines the width of the page for the generated PDF. You can specify the width using different units.

Supported Units:

px – pixel
in – inch
cm – centimeter
mm – millimeter

info

If no unit is specified, the value is interpreted as pixels.

Examples:

"width": 100 – sets the page width to 100 pixels.
"width": "100px" – sets the page width to 100 pixels.
"width": "10cm" – sets the page width to 10 centimeters.

Usage:

{
  "url": "https://example.com",
  "width": "15cm"
}

height

Type: string | number

Required: No

Details: Defines the height of the page for the generated PDF. For more information on supported units and examples, see width section.

Usage:

{
  "url": "https://example.com",
  "height": "800px"
}

margin

Type: object

Required: No

Details: Specifies the page margins for the generated PDF. By default, no margins are applied. When using this parameter, at least one margin property (top, right, left, bottom) must be provided. An empty margin object is invalid and will have no effect. For more information on supported units, see width section.

Property Name	Type	Description
`top`	`string` \| `number`	Specifies the top margin.
`right`	`string` \| `number`	Specifies the right margin.
`left`	`string` \| `number`	Specifies the left margin.
`bottom`	`string` \| `number`	Specifies the bottom margin.

Usage:

{
  "url": "https://example.com",
  "margin": {
    "top": "30px",
    "right": "20px",
    "left": "20px",
    "bottom": "30px"
  }
}

pageRanges

Type: string

Required: No

Details: Specifies the page ranges to include in the PDF. Accepts a comma-separated list of page ranges or individual pages, such as 1-3, 5, 8-11. If omitted, the PDF will include all pages by default.

Usage:

{
  "url": "https://example.com",
  "pageRanges": "1-7"
}

preferCssPageSize

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF generation should prioritize the CSS @page size defined in the content.

Value	Description
`true`	The PDF will use the dimensions specified in the `@page` CSS rule.
`false`	The content will scale automatically to fit the page size set by `width`, `height`, or `format`.

Usage:

{
  "url": "https://example.com",
  "preferCssPageSize": true
}

printBackground

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF should include background graphics like colors and images.

Value	Description
`true`	Background graphics (e.g., colors, images) will be included in the PDF.
`false`	Background graphics will be excluded, producing a simpler, more minimalistic PDF.

Usage:

{
  "url": "https://example.com",
  "printBackground": true
}

scale

Type: number

Required: No

Default Value: 1

Details: Specifies the scaling factor for rendering the content in the generated PDF. The acceptable range for this parameter is between 0.1 and 2.

Usage:

{
  "url": "https://example.com",
  "scale": 1.5
}

displayHeaderFooter

Type: boolean

Required: No

Default Value: false

Details: Specifies whether to include a header and footer in the generated PDF. This parameter is meaningful only when used with the headerTemplate and/or footerTemplate parameters to define the content of the header and footer.

Value	Description
`true`	Header and footer will be displayed on each page of the PDF.
`false`	No header or footer will be included in the PDF.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true
}

headerTemplate

Type: string

Required: No

Details: Specifies the HTML template for the page header. The template must be a valid Base64-encoded HTML string with specific classes used to dynamically inject values during PDF generation.

The following classes are used to inject values into them:

Placeholder	Description
`date`	Formatted date.
`title`	Document title.
`url`	Document location.
`pageNumber`	Current page number.
`totalPages`	Total number of pages in the document.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "headerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMHB4OyBjb2xvcjogZ3JheTsiPg0KICAgIDxzcGFuIGNsYXNzPSJ0aXRsZSI+PC9zcGFuPiB8IDxzcGFuIGNsYXNzPSJ1cmwiPjwvc3Bhbj4gfCA8c3BhbiBjbGFzcz0iZGF0ZSI+PC9zcGFuPg0KPC9kaXY+DQo=",
  "margin": {
      "top": "30px"
    }
}

This example generates a PDF with the following header:

<div style="width: 100%; text-align: center; font-size: 10px; color: gray;">
    <span class="title"></span> | <span class="url"></span> | <span class="date"></span>
</div>

info

Ensure that your HTML templates are valid Base64-encoded strings before using them.
Please note that <script> tags within templates are not executed.

Styling Tips

Apply Inline Styles: Use inline styles directly within your HTML templates, as CSS rules defined in the body do not affect headers or footers.
Adjust Margins: Modify the margin-top for headers and margin-bottom for footers to ensure visibility and avoid clipping.
Check Visibility: Verify font size, color, and background to make headers and footers clearly visible. Avoid using white text on a white background.

footerTemplate

Type: string

Required: No

Details: Specifies the Base64-encoded HTML template for the page footer. Use the same conventions as the headerTemplate.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "footerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMnB4OyI+DQogICAgPHNwYW4gY2xhc3M9InBhZ2VOdW1iZXIiPjwvc3Bhbj4gb2YgPHNwYW4gY2xhc3M9InRvdGFsUGFnZXMiPjwvc3Bhbj4NCjwvZGl2Pg==",
  "margin": {
      "bottom": "40px"
    }
}

This example generates a PDF with the footer:

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

Input Parameters​

html​

url​

Page Parameters​

emulateMediaType​

javaScriptEnabled​

httpCredentials​

viewportSize​

isMobile​

deviceScaleFactor​

extraHTTPHeaders​

cookies​

waitUntil​

waitForFunction​

waitForSelector​

timeout​

Pdf Layout​

format​

landscape​

width​

height​

margin​

pageRanges​

preferCssPageSize​

printBackground​

scale​

displayHeaderFooter​

headerTemplate​

footerTemplate​

Input Parameters

html

url

Page Parameters

emulateMediaType

javaScriptEnabled

httpCredentials

viewportSize

isMobile

deviceScaleFactor

extraHTTPHeaders

cookies

waitUntil

waitForFunction

waitForSelector

timeout

Pdf Layout

format

landscape

width

height

margin

pageRanges

preferCssPageSize

printBackground

scale

displayHeaderFooter

headerTemplate

footerTemplate