v1

latestSwagger 2.02026-07-1371041.4 KB

HTML To PDF

Convert HTML or URL to PDF

Converts a web URL or raw HTML string to PDF. Sync by default; set async=true to return a Job-Id immediately and poll /api2/asyncjob.

License key required. Success emits X-SelectPdf-Pages, X-SelectPdf-Mode: production, X-SelectPdf-Execution, and X-SelectPdf-Credits-Total / -Remaining.

post/api2/convert

Request body

keystring uuid required

License key. Required for /api2/convert; ignored on /api2/convert/demo.

asyncboolean

If true, submit asynchronously and return 202 + a Job-Id header. Poll /api2/asyncjob.

urlstring

Web URL to convert. Required if html is empty. Mutually exclusive with html.

htmlstring

Raw HTML string to convert. Required if url is empty.

base_urlstring

Base URL used to resolve relative paths inside html.

pdf_namestring

Filename suggested via Content-Disposition (default: Document.pdf).

page_size'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'Letter' | 'HalfLetter' | 'Ledger' | 'Legal'

Output page size.

page_orientation'Portrait' | 'Landscape'

page_widthinteger

Custom page width in points (1 pt = 1/72 in). Overrides page_size when both page_width and page_height are non-zero.

page_heightinteger

Custom page height in points.

margin_topinteger

Top margin in points.

margin_rightinteger

Right margin in points.

margin_bottominteger

Bottom margin in points.

margin_leftinteger

Left margin in points.

engine'WebKit' | 'Restricted' | 'Blink' | 'Chromium'

Rendering engine. WebKit (default) — broadest compatibility. Restricted — WebKit with limited JS. Blink — older Chromium fork. Chromium — modern Chromium/CEF (recommended for new integrations, required by the demo endpoint).

protocolinteger

TLS protocol selector for fetching url. 0 = default (negotiate).

web_page_widthinteger

Browser viewport width in pixels used while rendering.

web_page_heightinteger

Viewport height in pixels. 0 = automatic (engine picks based on content).

min_load_timeinteger

Minimum time (seconds) the engine waits after page load before producing the PDF (lets late-loading scripts settle).

max_load_timeinteger

Hard ceiling (seconds) for page load. On the demo endpoint this is clamped to 15.

use_css_printboolean

Honor CSS @media print rules instead of @media screen.

background_colorstring

PDF page background color (e.g. #FFFFFF).

draw_html_backgroundboolean

If false, the HTML's own backgrounds are stripped (transparent PDF).

disable_javascriptboolean

disable_internal_linksboolean

Suppress in-document anchor hyperlinks.

disable_external_linksboolean

Suppress hyperlinks pointing outside the document.

render_on_timeoutboolean

If max_load_time expires, render whatever loaded instead of failing.

keep_images_togetherboolean

Avoid splitting images across page breaks.

scale_imagesboolean

single_page_pdfboolean

Produce a single tall page sized to fit the entire content.

page_breaks_enhanced_algorithmboolean

doc_titlestring

PDF metadata: title.

doc_subjectstring

doc_keywordsstring

doc_authorstring

doc_add_creation_dateboolean

viewer_page_layout0 | 1 | 2 | 3 | 4 | 5

PDF viewer page layout: 0=SinglePage, 1=OneColumn (default), 2=TwoColumnLeft, 3=TwoColumnRight, 4=TwoPageLeft, 5=TwoPageRight.

viewer_page_mode0 | 1 | 2 | 3 | 4 | 5

PDF viewer page mode: 0=UseNone (default), 1=UseOutlines, 2=UseThumbs, 3=FullScreen, 4=UseOC, 5=UseAttachments.

viewer_center_windowboolean

viewer_display_doc_titleboolean

viewer_fit_windowboolean

viewer_hide_menu_barboolean

viewer_hide_toolbarboolean

viewer_hide_window_uiboolean

show_headerboolean

Render a header band on each page sourced from header_url or header_html.

header_display_on_first_pageboolean

header_display_on_odd_pagesboolean

header_display_on_even_pagesboolean

header_heightinteger

Header band height in points.

header_urlstring

URL whose rendered output becomes the page header.

header_htmlstring

Inline HTML used as the page header (alternative to header_url).

header_base_urlstring

header_web_page_widthinteger

header_web_page_heightinteger

show_footerboolean

footer_display_on_first_pageboolean

footer_display_on_odd_pagesboolean

footer_display_on_even_pagesboolean

footer_display_on_last_pageboolean

footer_heightinteger

footer_urlstring

footer_htmlstring

footer_base_urlstring

footer_web_page_widthinteger

footer_web_page_heightinteger

page_numbersboolean

Render page numbers in the footer band.

page_numbers_firstinteger

Page number assigned to the first page (lets you offset numbering).

page_numbers_offsetinteger

Number of leading pages to suppress numbering on.

page_numbers_templatestring

Template using {page_number} and {total_pages} placeholders.

page_numbers_font_namestring

page_numbers_font_sizeinteger

page_numbers_alignment1 | 2 | 3

1=Left, 2=Center, 3=Right.

page_numbers_colorstring

Hex color for the page numbers (e.g. #000000).

page_numbers_pos_yinteger

Vertical position of page numbers in points from the bottom.

pdf_bookmarks_selectorsstring

Semicolon-separated CSS selectors. Matched elements become PDF bookmarks.

pdf_hide_elementsstring

Semicolon-separated CSS selectors. Matched elements are hidden before rendering.

pdf_show_only_element_idstring

Render only the element with this id (everything else hidden).

pdf_web_elements_selectorsstring

Semicolon-separated CSS selectors whose bounding boxes are reported back via X-SelectPdf-Web-Elements (sync) or /api2/webelements (async).

user_passwordstring

Password required to open the PDF. Rejected by the demo endpoint.

owner_passwordstring

Password required to modify / print the PDF. Rejected by the demo endpoint.

auth_usernamestring

HTTP Basic-Auth username used when fetching url.

auth_passwordstring

cookiesobject

Cookie name → value map sent when fetching url (JSON body only).

cookies_stringstring

Query-string-encoded cookies (form / GET equivalent of cookies).

startup_modestring

Engine startup mode hint (automatic, manual).

skip_decodingboolean

If true, treat the URL as already-decoded (do not re-percent-decode). Internal default for forwarded calls.

raw_parametersstring

Optional JSON blob containing this entire object. When present, the receiver deserializes it and ignores all other form fields. Used by the SDK's remote-worker proxy.

response_content_type0 | 1

0 = binary/octet-stream (default, makes browsers download). 1 = application/pdf (browsers may render inline).

Example request

{
  "key": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "url": "https://selectpdf.com",
  "html": "<b>test html string</b>"
}

Response

PDF returned in the response body. X-SelectPdf-Pages carries the page count.