Render HTML to Image

Endpoint #

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

Action #

action=image

Description #

Renders HTML content as an image using the H2I engine (PixLab).

This action converts HTML layouts, templates, or dynamically generated markup into static image output. It is one of the core capabilities of Davix H2I and is suitable for workflows such as generated reports, social media graphics, previews, certificates, and other rendered visual assets.

Request Format #

Send the request as JSON.

The /v1/h2i route accepts JSON and URL-encoded bodies, but JSON is the recommended format for this action.

Parameters #

action #

Type: string
Required: Yes
Accepted value: image

Selects image output mode for the /v1/h2i route.

html #

Type: string
Required: Yes

The HTML content to render.

This is the required render source for the HTML-to-image flow. Missing html returns missing_field. Oversized HTML returns html_too_large.

css #

Type: string
Required: No
Default: empty string

Optional CSS string applied together with the HTML render request.

width #

Type: integer
Required: No
Default: 1000

Viewport width for rendering.

The route clamps width to the allowed render width range rather than rejecting oversized width values directly.

height #

Type: integer
Required: No
Default: 1500

Viewport height for rendering.

The route clamps height to the allowed render height range rather than rejecting oversized height values directly.

format #

Type: string
Required: No
Default: png

Controls the output image encoding.

The loaded public docs confirm PNG as the default, and that JPEG output is produced when the image format is explicitly set to JPEG.

Full cURL Example #

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": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Report</title></head><body><div class=\"card\"><h1>Quarterly Report</h1><p>Generated with Davix H2I</p></div></body></html>",
    "css": "html,body{margin:0;padding:0;background:#f5f7fb;font-family:Arial,sans-serif}.card{width:1000px;height:1500px;display:flex;flex-direction:column;align-items:center;justify-content:center;background:#ffffff;color:#111827}",
    "width": 1000,
    "height": 1500,
    "format": "png"
  }'

This matches the documented external /v1/h2i image request model: authenticated JSON body, optional idempotency header, and the verified HTML render fields for image mode.

Success Response #

Successful requests return HTTP 200.

Response body #

{
  "url": "https://pixlab.davix.dev/h2i/<generated-file>?exp=<...>&sig=<...>",
  "request_id": "<REQUEST_ID>"
}
  • url points to the generated H2I image output.
  • request_id may be present and can be used for tracing, debugging, and support.

Generated H2I outputs are served from the public /h2i/* output path, and signed URL query parameters are used when signed output access is enabled.

Errors #

The loaded public docs support these common errors for /v1/h2i image rendering:

  • invalid_parameter
  • missing_field
  • html_too_large
  • pixel/render-size limit error for oversized render area
  • rate_limit_exceeded
  • rate_limit_store_unavailable
  • monthly_quota_exceeded
  • server_busy
  • timeout
  • html_render_failed

Authentication and idempotency-related errors can also occur, including:

  • invalid_api_key
  • key_expired
  • api_key_location_not_allowed
  • invalid_idempotency_key

The only point that needs caution is the exact code name for the oversized render-area failure: one loaded file names it render_size_exceeded, while another names it render_too_large. The source files are inconsistent on that single detail and should be reconciled before you publish the exact code string on this page.

Usage Notes #

  • action=image is the image-render mode of /v1/h2i.
  • html is required for this action. Missing html returns missing_field.
  • HTML size is limited. Oversized HTML returns html_too_large.
  • Width and height are clamped to the configured render bounds.
  • If the final render area exceeds the allowed pixel limit after width and height handling, 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.
  • Idempotency-Key and X-Idempotency-Key are optional and supported for safer retries and request correlation. Valid idempotency keys are echoed back in the Idempotency-Key response header.
Was it helpful ?
Table of contents
Login
Login
Login
Login
Scroll to Top