Generate Open Graph Images

Overview #

Davix H2I can generate dynamic preview-style images by rendering HTML layouts into image output through the public HTML-rendering endpoint. Requests sent to Davix H2I are executed by the H2I engine (PixLab), which renders the HTML and returns a generated image URL. HTML-to-image rendering is one of the defining capabilities of the platform and supports workflows based on templates, generated content, and automated visual assets.

This recipe is appropriate when an application or CMS needs to generate a consistent image layout dynamically from content and retrieve the rendered output through the API. Davix H2I provides that rendering capability as a backend service instead of requiring each application to maintain its own rendering stack.

Workflow #

A typical image-generation workflow looks like this:

1. Generate an HTML template containing dynamic content.
2. Send that HTML to POST /v1/h2i.
3. Set action to image.
4. Receive a rendered output URL in the API response.
5. Use the returned image URL in the application’s own publishing or content workflow.

When to use this recipe #

This workflow is suitable for application-driven visual asset generation where content is inserted into an HTML template and rendered automatically. The broader Davix H2I docs support use cases such as dynamic marketing assets, template-based content generation, and automated visual outputs.

Example architecture #

Typical image-generation flow:

Application / CMS
        │
        │ generate HTML template
        │
        ▼
Davix H2I API
https://pixlab.davix.dev/v1/h2i
        │
        │ HTML rendered by
        │ H2I engine (PixLab)
        │
        ▼
Generated Image URL
        │
        ▼
Used by the application workflow

This reflects the documented Davix H2I model in which the client sends an authenticated request, the backend engine performs the render, and the result is returned as a generated file URL.

Step 1 — Create an HTML template #

Davix H2I accepts HTML layouts, templates, and dynamically generated markup as input to the H2I rendering workflow. A template can therefore be built as a fixed HTML layout and populated with dynamic content before sending it to the API.

Example template:

<div style="
width:100%;
height:100%;
display:flex;
flex-direction:column;
justify-content:center;
align-items:center;
background:#111827;
color:white;
font-family:Arial, sans-serif;
text-align:center;
padding:80px;
box-sizing:border-box;
">
  <h1 style="font-size:64px;margin-bottom:20px;">
    Dynamic Article Title
  </h1>
  <p style="font-size:32px;color:#9CA3AF;">
    Automatically generated preview image
  </p>
</div>

The application or CMS would replace the example content values before sending the request.

Step 2 — Send the rendering request #

Endpoint:

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

The /v1/h2i endpoint is the public HTML-rendering route. It accepts JSON or URL-encoded bodies, supports both image and pdf actions, and requires API key authentication. This recipe uses the image action.

Authentication is accepted through:

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

In production, body-based api_key and query-based ?key= authentication are rejected.

Full example request #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: og-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;background:#111827;color:white;font-size:60px\">Hello</div>",
    "css": "body{margin:0}",
    "width": 1200,
    "height": 630,
    "format": "jpeg"
  }'

This uses the full documented public parameter set for the /v1/h2i image action:

• action
• html
• css
• width
• height
• format

Request parameters #

Parameter	Required	Description
action	yes	Must be image for image output
html	yes	HTML content to render
css	no	Additional CSS injected into the rendered document
width	no	Render width
height	no	Render height
format	no	Output format

Documented route behavior for image mode:

• width defaults to 1000
• height defaults to 1500
• format defaults to png
• format=jpeg yields JPEG output; other values become PNG

Example success response #

A successful /v1/h2i request returns a generated URL in this shape:

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

The documented success shape for this route family is { url, request_id? }, so url is required and request_id may also be included.

Output behavior #

H2I outputs are returned through the /h2i/* output path. Generated output URLs are built through the signed URL system, and guarded output fetches require valid signature parameters when signed URL enforcement is enabled. Clients should use the returned url directly rather than constructing output URLs manually.

Using the generated image #

After the API returns the image URL, the calling application can store that URL or use it in its own publishing workflow. Davix H2I generates the output file; downstream distribution and page metadata usage are handled by the application. This aligns with the platform’s role as a backend processing layer rather than a long-term storage or file-hosting platform.

Automation workflow #

A common automation pattern is:

Content published
        │
        ▼
Generate HTML template
        │
        ▼
Call Davix H2I API
        │
        ▼
Store generated image URL
        │
        ▼
Use URL in the application workflow

This aligns with the broader Davix H2I documentation describing API-based automation workflows, template-based generation, and backend processing used inside larger systems.

Rendering limits #

The /v1/h2i route applies documented rendering controls, including:

• HTML length cap
• render width cap
• render height cap
• render pixel-area cap

The canonical limits documentation shows:

• HTML over the cap returns html_too_large
• width and height are clamped to configured ceilings
• pixel-area overflow is rejected

The loaded docs are not fully aligned on the exact name of the render-size failure:

• the error architecture uses render_size_exceeded
• the limits doc describes the H2I pixel-area failure as render_too_large

Because of that mismatch, this page should describe that case neutrally as a render-size limit error until the source docs are unified.

Since you want numeric limits centralized under Errors and Limits, this page should link there instead of repeating limit values here.

Summary #

This recipe demonstrates how to generate dynamic image assets using Davix H2I’s HTML-to-image workflow.

The documented flow is:

• create an HTML layout
• send it to POST /v1/h2i
• render the image through the H2I engine (PixLab)
• receive a generated output URL in response