Generating Images from HTML Templates

Overview #

Davix H2I can generate images directly from HTML by sending a request to POST /v1/h2i with action=image. Requests sent to Davix H2I are executed by the H2I engine (PixLab), which renders the HTML and returns a generated output URL. HTML rendering is one of the platform’s core capabilities and is a primary way to turn dynamic layouts into backend-generated assets.

This workflow is useful when your application already produces layouts in HTML and needs to convert them into image files for automated generation, reporting, content production, or other backend processes. Instead of operating your own rendering infrastructure, your application sends the HTML to Davix H2I and receives a generated file URL in response.

How the workflow works #

The HTML-to-image workflow follows a request-response model:

1. Your application builds an HTML string.
2. Your application sends that HTML to POST /v1/h2i.
3. The request is authenticated with an API key.
4. The request sets action to image.
5. The H2I engine (PixLab) renders the HTML and writes the generated output file.
6. The API returns a JSON response containing a generated URL in url.

Endpoint used #

POST https://pixlab.davix.dev/v1/h2i

The external HTML rendering endpoint is POST /v1/h2i. It accepts JSON and URL-encoded request bodies, requires API key authentication, and returns JSON. The endpoint supports both image and pdf actions; this guide covers the image workflow.

Authentication #

External /v1/* routes accept authentication in either of these header forms:

• X-Api-Key: <key>
• Authorization: Bearer <key>

In non-production environments, the backend also accepts body-based api_key and query-based ?key=. In production, those locations are explicitly rejected with api_key_location_not_allowed. Public integrations should always send the API key in headers.

Required parameters #

For HTML-to-image generation, the request requires:

• action — must be image
• html — the HTML content to render

Optional parameters for image generation include:

• css
• width
• height
• format

The documented route behavior is:

• width defaults to 1000
• height defaults to 1500
• format defaults to png
• format=jpeg produces JPEG output
• other format values produce PNG output for this route behavior

Response format #

A successful /v1/h2i image request returns this shape:

{
  "url": "https://pixlab.davix.dev/h2i/<generated-file>",
  "request_id": "<REQUEST_ID>"
}

In the external API reference, the success shape is defined as { url, request_id? }, so url is the main response field and request_id may also be included.

Output URL behavior #

Generated H2I files are served from the /h2i/* output path. File-producing routes build output URLs through the signed URL system, and static fetches on /h2i/* are protected by the signed static guard when signed output enforcement is enabled. You should use the url returned by the API response directly rather than constructing output URLs yourself.

Example request #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: h2i-image-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "image",
    "html": "<div style=\"width:100%;height:100%;display:flex;align-items:center;justify-content:center\">Hello</div>",
    "css": "body{margin:0}",
    "width": 1200,
    "height": 1600,
    "format": "jpeg"
  }'

This example matches the documented external example for POST /v1/h2i with action=image.

Example success response #

{
  "url": "https://pixlab.davix.dev/h2i/<generated-image>?exp=<SIGNED_EXPIRY>&sig=<SIGNED_SIGNATURE>",
  "request_id": "<REQUEST_ID>"
}

The exact filename is generated by the backend. H2I file outputs are returned under the /h2i/<file> path and are signed through the platform’s output URL system.

Parameter reference for this workflow #

Field	Required	Type	Notes
action	yes	string	Must be image
html	yes	string	HTML source to render
css	no	string	CSS string applied during render
width	no	integer-ish	Defaults to 1000; values above the render ceiling are clamped
height	no	integer-ish	Defaults to 1500; values above the render ceiling are clamped
format	no	string	jpeg yields JPEG; other values become PNG

This behavior is documented in the external API reference and limits docs for /v1/h2i.

Important behavior #

The /v1/h2i route is protected by the standard external API enforcement chain, including API key validation, endpoint gating, timeout handling, rate limiting, concurrency control, and customer quota handling.

For H2I rendering specifically, the platform enforces these render-related controls:

• maximum HTML size
• maximum render width
• maximum render height
• maximum render pixel area
• request timeout
• concurrency limits

This guide should not publish the numeric limits directly if you want all customer-facing limits centralized under Errors and Limits. In this page, link to that limits page instead of repeating values here.

Two implementation details are important:

• render width and height are clamped to the configured maximums
• render pixel-area overflow is rejected after clamping

Errors you may encounter #

Documented error codes relevant to this workflow include:

• invalid_parameter
• missing_field
• html_too_large
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout
• html_render_failed
• authentication and idempotency errors such as invalid_api_key, key_expired, api_key_location_not_allowed, and invalid_idempotency_key

For render-size failures, the loaded source documents are not fully aligned:

• the error architecture doc lists render_size_exceeded
• the limits doc describes H2I pixel-area overflow as render_too_large

Because of that mismatch, this guide should not hard-assert only one render-size code until the source docs are unified.

Example error response #

{
  "status": "error",
  "code": "missing_field",
  "message": "Missing required field",
  "error": {
    "code": "missing_field",
    "message": "Missing required field"
  },
  "request_id": "<REQUEST_ID>"
}

This matches the standard external JSON error envelope used by sendError(...), including request_id.

When to use this guide #

Use this workflow when your system already generates HTML dynamically and needs a backend service to turn that HTML into image output. This is one of the central rendering patterns supported by Davix H2I and one of the main ways the platform is used in automated generation workflows.