Endpoint #
POST https://pixlab.davix.dev/v1/h2i
Action #
action=pdf
Description #
Renders HTML content into a PDF document using the H2I engine (PixLab).
Applications can send HTML layouts or dynamically generated markup and request that the service convert the content into a PDF document. This capability is commonly used for reports, invoices, certificates, and other structured documents generated from HTML templates. HTML-to-PDF is one of the central capabilities of Davix H2I.
Request Format #
Send the request as JSON.
The /v1/h2i endpoint accepts JSON and URL-encoded bodies, but JSON is the recommended format for HTML rendering operations.
Parameters #
action #
Type: string
Required: Yes
Accepted value: pdf
Selects PDF output mode.
html #
Type: string
Required: Yes
HTML markup to render as a PDF document.
Missing html returns missing_field. Oversized HTML returns html_too_large.
css #
Type: string
Required: No
Default: empty string
Optional CSS string applied with the HTML render request.
width #
Type: integer
Required: No
Default: 1000
Viewport width used during HTML rendering.
The value is clamped to the allowed render width.
height #
Type: integer
Required: No
Default: 1500
Viewport height used during HTML rendering.
The value is clamped to the allowed render height.
pdfFormat #
Type: string
Required: No
Default: A4
Controls the PDF page format.
If the value is LETTER (case-insensitive), the page size becomes Letter. All other values resolve to A4.
pdfLandscape #
Type: boolean or boolean-like string
Required: No
Default: false
Controls page orientation. When enabled, pages are generated in landscape mode.
pdfMargin #
Type: integer
Required: No
Default: 24
Sets the page margin for the generated PDF document. The value is parsed as an integer.
preferCSSPageSize #
Type: boolean
Required: No
Default: true
If enabled, the renderer prefers page sizing defined in CSS rules instead of the default PDF page configuration.
scale #
Type: number
Required: No
Default: 1
Scaling factor applied to the rendered output.
printMode #
Type: boolean
Required: No
Default: false
Controls whether the page should be rendered using print-style rendering behavior.
printBackground #
Type: boolean
Required: No
Default: true
Controls whether background graphics and colors defined in the HTML or CSS are included in the rendered PDF output.
Full cURL Example #
curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
-H "X-Api-Key: <YOUR_API_KEY>" \
-H "Idempotency-Key: h2i-pdf-001" \
-H "Content-Type: application/json" \
-d '{
"action": "pdf",
"html": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Invoice</title></head><body><main class=\"page\"><h1>Invoice</h1><p>Generated with Davix H2I</p></main></body></html>",
"css": "html,body{margin:0;padding:0;font-family:Arial,sans-serif}.page{padding:40px;color:#111827}",
"width": 1000,
"height": 1500,
"pdfFormat": "A4",
"pdfLandscape": false,
"pdfMargin": 24,
"preferCSSPageSize": true,
"scale": 1,
"printMode": false,
"printBackground": true
}'
This matches the documented external /v1/h2i PDF-mode request model.
Success Response #
Successful requests return HTTP 200.
Response body #
{
"url": "https://pixlab.davix.dev/h2i/<generated-file>?exp=<...>&sig=<...>",
"request_id": "<REQUEST_ID>"
}
urlpoints to the generated PDF output file.request_idmay be present and can be used for request tracking.
Generated H2I outputs are served from the public /h2i/* output path.
Errors #
The documented public /v1/h2i errors include:
invalid_parametermissing_fieldhtml_too_large- render-size limit error for oversized render area
rate_limit_exceededrate_limit_store_unavailablemonthly_quota_exceededserver_busytimeouthtml_render_failed
Authentication and idempotency errors can also occur, including:
invalid_api_keykey_expiredapi_key_location_not_allowedinvalid_idempotency_key
The only wording caution is the exact render-size error code name, because the loaded sources are not fully consistent on that one item.
Usage Notes #
Idempotency-Key is optional and supported for safer retries. The platform also accepts X-Idempotency-Key, validates the value, and echoes a valid idempotency key in the Idempotency-Key response header.
Width and height are clamped by the service to the allowed render limits.
If the final render area exceeds the allowed render pixel limit, the request fails with the route’s render-size limit error.
The endpoint requires API key authentication. Both X-Api-Key and Authorization: Bearer <key> are supported. In production, body api_key and query ?key= are rejected.
