Skip to main content

HTML to PDF

Parameters

NameTypeRequiredDescriptionDefault
idStringNoUnique request identifierUUID
htmlStringYesHTML content to print
pdfObjectNoPDF parameters
headerTemplateStringNoHeader
footerTemplateStringNoFooter
displayHeaderFooterBooleanNoWhen true, header and footer will be displayedfalse
generateTaggedPdfBooleanNoGenerate a tagged PDF, useful for accessible PDFsfalse
generateDocumentOutlineBooleanNoGenerate a PDF with outline. Requires generateTaggedPdf to be truefalse
optionsObjectNoPrinting options
waitUntilStringNoload: wait for load event
domcontentloaded: wait for DOMContentLoaded event
manual: wait for manual print signal
load
timeoutLongNoPrint timeout, unit: milliseconds15000
tip

All strings support UTF-8. For complex HTML, inline CSS/JS is recommended to avoid loading delays.

Request Body

{
"id": "43eaf69a-194a-4c0f-8e38-726f09eb24ba",
"html": "<html><body>Hi, bkhtmltopdf.</body></html>",
"pdf": {
"footerTemplate": "",
"headerTemplate": "",
"displayHeaderFooter": false,
"generateTaggedPdf": true,
"generateDocumentOutline": true
},
"options": {
"waitUntil": "load"
}
}

Response Body

The API returns a PDF stream (Content-Type: application/pdf), which can be directly displayed or saved in a browser or HTTP client.

cURL

curl 'http://localhost:8080/html-to-pdf' \
-H 'Content-Type: application/json' \
--data-raw '{"id":"43eaf69a-194a-4c0f-8e38-726f09eb24ba","html":"<html><body>Hi, bkhtmltopdf.</body></html>","pdf":{"footerTemplate":"","headerTemplate":"","displayHeaderFooter":false,"generateTaggedPdf":true,"generateDocumentOutline":true},"options":{"waitUntil":"load"}}' \
--output bkhtmltopdf.pdf

After execution, bkhtmltopdf.pdf will be generated in the current directory.

manual

The manual mode allows you to customize when rendering is considered complete, which is especially useful when integrating libraries like Paged.js. Add a script in your HTML to trigger it manually:


<script>
window.addEventListener('DOMContentLoaded', () => {
// 仅在 waitUntil 等于 manual 时生效
console.debug('print')
})
</script>
  • Mechanism: The service waits for the console.debug('print') log. If not received within 15 seconds, it will timeout and throw an error.
  • Purpose: Ensures JS/CSS pagination is complete, preventing incomplete page printing.
  • Note: Only effective when waitUntil: "manual" is set.