Generating Social Media Images

Overview #

Davix H2I can generate social media images from HTML templates by sending a request to the HTML-rendering endpoint and returning an image output. This is a natural use of the platform because Davix H2I is built to convert HTML into images or PDFs through a backend API workflow, with processing executed by the H2I engine (PixLab). The broader product documentation explicitly describes HTML rendering as a foundational capability and includes dynamic marketing assets and template-based image generation among its supported use cases.

This guide explains how to use that workflow to create image assets for social sharing, content previews, visual cards, and other generated media that can be designed in HTML and rendered into a static image file.

Why use HTML for social media images #

HTML-based rendering is useful when the image layout needs to be generated dynamically from application data or reusable templates. The loaded docs support HTML layouts, templates, and dynamically generated markup as inputs to Davix H2I, which can then render them into static image outputs through the public API.

This pattern is especially relevant when the same design needs to be reused with different content values. Davix H2I provides the rendering layer as an API-accessible service so applications can integrate that capability without operating their own backend rendering infrastructure.

How the workflow works #

A typical social-image workflow looks like this:

  1. Your application builds an HTML template for the image.
  2. Your application inserts dynamic content into that template.
  3. Your application sends the rendered HTML to POST /v1/h2i.
  4. The request sets action to image.
  5. The H2I engine (PixLab) renders the HTML into an image file.
  6. The API returns a JSON response containing the generated output URL.

Endpoint used #

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

The /v1/h2i route is the documented public endpoint for HTML rendering. It accepts JSON or URL-encoded request bodies, returns JSON responses, and supports both image and pdf actions. This guide focuses on the image workflow.

Authentication #

External /v1/* routes require API key authentication. Supported authentication methods are:

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

In production, body-based api_key and query-based ?key= authentication are rejected, so public integrations should authenticate through headers.

Required request fields #

For this workflow, the request must include:

  • action with the value image
  • html containing the image layout

Optional fields include:

  • css
  • width
  • height
  • format

The external H2I API reference documents this image-mode behavior and notes that format defaults to png, while jpeg yields JPEG output and other values fall back to PNG. Defaults for render size are width=1000 and height=1500.

Basic HTML template pattern #

A social media image is typically built as a single HTML layout sized to the intended render area. Davix H2I renders the resulting HTML into an image output through the /v1/h2i image workflow.

Example template structure:

<html>
<head>
  <style>
    body {
      margin: 0;
      font-family: Arial, sans-serif;
    }
    .card {
      width: 100%;
      height: 100%;
      display: flex;
      align-items: center;
      justify-content: center;
      text-align: center;
      padding: 40px;
      box-sizing: border-box;
    }
    .title {
      font-size: 48px;
      line-height: 1.2;
    }
  </style>
</head>
<body>
  <div class="card">
    <div class="title">Dynamic Social Media Image</div>
  </div>
</body>
</html>

Your application would generate the final HTML string dynamically before sending it to the API.

Example API request #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: social-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\">Dynamic Social Media Image</div>",
    "css": "body{margin:0;font-family:Arial,sans-serif}",
    "width": 1200,
    "height": 630,
    "format": "jpeg"
  }'

This uses the documented public parameter set for the /v1/h2i image action: action, html, css, width, height, and format.

Example success response #

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

The documented success shape for /v1/h2i is { url, request_id? }, so url is the required response field and request_id may also be included. H2I-generated outputs are served from /h2i/* and returned through the platform’s signed output URL system.

Output behavior #

Generated H2I files are written under the H2I output path and returned through a generated URL. The public route inventory and lifecycle docs confirm that H2I output files are served from /h2i/* and protected by signed URL handling when signed output enforcement is enabled. Clients should use the returned url directly rather than constructing file paths themselves.

Parameter reference for social-image generation #

FieldRequiredTypeNotes
actionyesstringMust be image
htmlyesstringHTML source to render
cssnostringCSS injected into the rendered document
widthnointeger-ishDefaults to 1000; values above the render ceiling are clamped
heightnointeger-ishDefaults to 1500; values above the render ceiling are clamped
formatnostringjpeg yields JPEG; other values become PNG

This parameter behavior is documented in the external H2I API reference and public route inventory.

Designing reusable templates #

For social media image generation, a practical pattern is to build reusable HTML templates and fill them with dynamic content from your application. The product documentation explicitly supports rendering HTML layouts, templates, and dynamically generated markup into image outputs, which makes this a natural workflow for repeated asset generation.

A common implementation pattern is:

  • one reusable HTML layout
  • one CSS style layer
  • one dynamic content block
  • one render request per generated image

That is an application-level pattern built on the supported HTML-to-image API workflow.

Limits and validation #

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

  • HTML length checks
  • render width controls
  • render height controls
  • pixel-area checks
  • timeout handling
  • concurrency handling
  • quota handling for customer keys

The canonical H2I lifecycle and plans documentation also show that:

  • width and height are clamped to configured ceilings
  • render-area overflow is rejected
  • H2I behavior is controlled by plan- and runtime-level render caps such as maximum HTML length, render width, render height, and render pixels

Because you want customer-facing numeric limits centralized in one place, this page should link to your Errors and Limits section instead of repeating limit values here.

Errors you may encounter #

Relevant documented error codes for 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-related errors can also apply, including:

  • invalid_api_key
  • key_expired
  • api_key_location_not_allowed
  • invalid_idempotency_key

For render-size failures, the loaded documentation is not fully normalized. The external API reference lists render_size_exceeded, while the lifecycle/limits-side material describes pixel-area overflow without a single fully unified public name. Public docs should avoid overcommitting to one named render-size error until the source docs are unified.

Example error response #

{
  "status": "error",
  "code": "html_render_failed",
  "message": "Rendering process failed",
  "error": {
    "code": "html_render_failed",
    "message": "Rendering process failed"
  },
  "request_id": "<REQUEST_ID>"
}

This matches the canonical standard API error envelope, which includes top-level status, code, and message, nested error.code and error.message, and typically request_id.

Best practices #

Log the returned request_id when present for troubleshooting.

Treat output URLs as generated backend assets instead of assuming a fixed filename.

Use a reusable HTML template so only content values change between requests.

Keep the layout simple and deterministic for predictable rendering.

Use CSS injection for edge-to-edge layouts when needed, such as body{margin:0}.

Was it helpful ?
Table of contents
Login
Login
Login
Login
Scroll to Top