Conversion Parameters

Our API offers flexible HTML to PDF conversion tailored to different workflow needs. Below, you’ll find an overview of each mode, so you can select the one that best fits your project.

Input Parameters

html

Type: string

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

Details: Accepts Base64-encoded HTML content. This allows directly providing the HTML for PDF generation.

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.

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

Usage:

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

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: Specifies the device scale factor, determining the level of scaling applied to the webpage content during rendering.

Usage:

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

extraHTTPHeaders

Type: object

Required: No

Details: Specifies additional HTTP headers to include in the request. This can be used to pass custom headers. 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 and value fields, with optional properties available for further customization.

Property Name	Type	Description
`name`	`string`	The name of the cookie. `required`
`value`	`string`	The value of the cookie. `required`
`domain`	`string`	The domain for which the cookie is valid. `optional`
`path`	`string`	The URL path that must exist in the requested URL for the cookie to be sent. `optional`
`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": "exampleName",
      "value": "exampleValue"
    }
  ]
}

waitUntil

Type: string

Required: No

Default Value: load

Details: Defines the event that determines when the page is considered successfully loaded.

Allowed Values:

Value	Description
`domcontentloaded`	Operation finishes when the `DOMContentLoaded` event is fired.
`load`	Operation finishes when the `load` event is fired.
`networkidle`	Operation finishes when there are no network connections for at least 500 ms.
`commit`	Operation finishes when the document starts loading and a network response is received.

Usage:

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

waitForFunction

Type: string

Required: No

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

Usage:

{
  "url": "https://example.com",
  "waitForFunction": "() => window.innerWidth < 100"
}

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. Defaults to `visible`. `required`

Allowed Values for state:

Value	Description
`attached`	Wait for the element to be present in the DOM.
`detached`	Wait for the element to not be present in the DOM.
`visible`	Wait for the element to have a non-empty bounding box and not have `visibility: hidden`. Elements with `display: none` are excluded.
`hidden`	Wait 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": "img",
    "state": "visible"
  }
}

timeout

Type: number

Required: No

Default Value: 30000

Details: Defines the maximum time in milliseconds to wait for the page to load. Acceptable range is between 0 and 60000 (1 minute).

Usage:

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

Pdf Layout

format

Type: string

Required: No

Default Value: Letter

Details: Specifies the paper format for the PDF. If set, this option takes priority over width or height settings.

Allowed Values: The following table lists the supported paper formats and their dimensions:

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: Specifies the page orientation.

Value	Description
`true`	The PDF is generated in landscape mode.
`false`	The PDF is generated in portrait mode (default).

Usage:

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

width

Type: string | number

Required: No

Details: Specifies the width of the page for the generated PDF.

Supported Units:

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

info

Unlabeled values are treated 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": "100cm"
}

height

Type: string | number

Required: No

Details: Specifies 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": "100cm"
}

margin

Type: object

Required: No

Details: Specifies the margins of the page. By default, no margins are applied. For more information on supported units, see width section.

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

Usage:

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

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 scale of the content rendering for the PDF. The scale value must be between 0.1 and 2.

Usage:

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

displayHeaderFooter

Type: boolean

Required: No

Default Value: false

Details: Specifies whether to include a header and footer in the generated PDF.

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. This template must be a valid base64-encoded HTML string.

The following placeholders are dynamically replaced during PDF generation:

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": "PGRpdiBzdHlsZT0iZm9udC1zaXplOiAxMHB4OyB0ZXh0LWFsaWduOiBjZW50ZXI7Ij4KICAgIDxzcGFuIHN0eWxlPSJjb2xvcjogZ3JheTsiPnt0aXRsZX0gfCB7dXJsfSB8IHtkYXRlfTwvc3Bhbj4KPC9kaXY+Cg=="
}

This example generates a PDF with the following header:

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

info

Apply styles directly within the HTML templates, as CSS defined in the body does not affect the header and footer.
Please note that <script> tags within templates are not executed.
If headers or footers are not visible, try adjusting the margin-top for headers and margin-bottom for footers. Ensure these margins are large enough to accommodate the template content if necessary. Additionally, headers and footers might use white text on a white background or have very small font sizes, making them difficult to see. Consider applying styling to enhance their visibility.

footerTemplate

Type: string

Required: No

Details: HTML template for the page footer should follow the same format and conventions. For more details, see headerTemplate section.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "footerTemplate": "PGRpdiBzdHlsZT0iZm9udC1zaXplOiAxMHB4OyB0ZXh0LWFsaWduOiBjZW50ZXI7Ij4KICAgIDxzcGFuIHN0eWxlPSJjb2xvcjogZ3JheTsiPntwYWdlTnVtYmVyfSBvZiB7dG90YWxQYWdlc308L3NwYW4+CjwvZGl2Pgo="
}

This example generates a PDF with footer:

<div style="font-size: 10px; text-align: center;">
  <span style="color: gray;">{pageNumber} of {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