Creating Certificates

Overview #

Davix H2I can be used to generate certificates automatically by rendering HTML templates into image or PDF outputs. In this workflow, an application creates a certificate layout in HTML, inserts dynamic values such as the recipient name or certificate title, and sends that HTML to Davix H2I for rendering. The rendering process is executed by the H2I engine (PixLab), which converts the HTML template into the final output file.

Because /v1/h2i supports both image and pdf actions, the same certificate template can be rendered into different output formats depending on how the application needs to use the result.

When certificate generation is useful #

Certificate generation is a natural HTML-rendering use case for systems that need to produce fixed-layout documents automatically from dynamic data. The loaded Davix H2I documentation supports automated document generation, template-based output generation, and HTML-based document rendering as core platform workflows.

Common application examples include:

  • completion certificates
  • training certificates
  • participation certificates
  • membership certificates
  • recognition documents

These are application patterns built on the platform’s documented HTML-rendering capability, not separate product features.

How the certificate workflow works #

A typical certificate workflow follows these steps:

  1. The application creates an HTML certificate template.
  2. Dynamic values such as recipient name or event title are inserted into the template.
  3. The rendered HTML is sent to POST /v1/h2i.
  4. The request sets the desired output type with action=image or action=pdf.
  5. The H2I engine (PixLab) renders the certificate.
  6. The API returns a signed URL pointing to the generated certificate file.

This allows applications to generate certificates automatically without operating their own HTML-rendering infrastructure.

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, requires API key authentication, supports both image and pdf actions, and returns JSON with a generated output URL in url.

Authentication #

External /v1/* routes accept authentication through:

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

In non-production environments, body-based api_key and query-based ?key= are also accepted. In production, those locations are rejected with api_key_location_not_allowed. Public integrations should authenticate through headers.

Certificate template design #

Certificates are usually built as fixed HTML layouts. Because Davix H2I renders HTML content, the template can be designed with standard HTML and CSS and then populated dynamically before sending it to the API.

Example certificate template:

<html>
<head>
  <style>
    body {
      margin: 0;
      font-family: serif;
    }
    .certificate {
      width: 100%;
      height: 100%;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    .content {
      text-align: center;
    }
    .title {
      font-size: 48px;
      margin-bottom: 20px;
    }
    .name {
      font-size: 36px;
      margin: 20px 0;
    }
    .description {
      font-size: 18px;
    }
  </style>
</head>
<body>
  <div class="certificate">
    <div class="content">
      <div class="title">Certificate of Completion</div>
      <div class="description">This certificate is awarded to</div>
      <div class="name">Recipient Name</div>
      <div class="description">for successfully completing the program</div>
    </div>
  </div>
</body>
</html>

In a real system, the application would replace Recipient Name and other fields before sending the HTML to Davix H2I.

Rendering certificates as images #

If the certificate should be used as a visual asset in an application interface or content workflow, it can be rendered as an image through /v1/h2i with action=image.

Required fields for image mode #

FieldDescription
actionMust be image
htmlHTML content to render

Optional fields for image mode #

FieldDescription
cssCSS styles injected into the rendered document
widthRender width
heightRender height
formatOutput image format

Documented defaults for image mode:

  • width: 1000
  • height: 1500
  • format: png

format=jpeg yields JPEG output; other values become PNG.

Full image generation request #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: certificate-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\">Certificate</div>",
    "css": "body{margin:0}",
    "width": 1200,
    "height": 900,
    "format": "png"
  }'

This uses the full public parameter set for the /v1/h2i image action as documented in the external reference and examples.

Rendering certificates as PDFs #

If the certificate should be delivered as a document file, /v1/h2i can render the same HTML into PDF output by setting action=pdf.

Required fields for PDF mode #

FieldDescription
actionMust be pdf
htmlHTML content to render

Optional fields for PDF mode #

FieldDescription
cssCSS applied during rendering
widthRender width
heightRender height
pdfFormatPage format
pdfLandscapeLandscape orientation
pdfMarginPage margin
preferCSSPageSizeUse CSS page-size preference
scalePage scaling factor
printModePrint-oriented render mode
printBackgroundEnables CSS background rendering

Documented defaults for PDF mode:

  • pdfFormat: A4
  • pdfLandscape: false
  • pdfMargin: 24
  • preferCSSPageSize: true
  • scale: 1
  • printMode: false
  • printBackground: true

Full PDF generation request #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: certificate-pdf-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "pdf",
    "html": "<html><body><h1>Certificate of Completion</h1></body></html>",
    "css": "body{font-family:serif}",
    "width": 1000,
    "height": 1500,
    "pdfFormat": "LETTER",
    "pdfLandscape": false,
    "pdfMargin": 24,
    "preferCSSPageSize": true,
    "scale": 1,
    "printMode": false,
    "printBackground": true
  }'

This uses the full public parameter set for the /v1/h2i PDF action.

Example success response #

A successful certificate-rendering request returns JSON containing the generated output URL.

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

The documented success shape is { url, request_id? }, so url is required and request_id may also be included. H2I-generated outputs are served under /h2i/* and returned through the signed output URL system.

Handling certificate output #

After a certificate is generated, the application can use the returned output URL in its own workflow. Typical downstream uses include:

  • providing a download link
  • storing the returned URL
  • displaying the generated certificate in an application
  • passing the file URL to another system or workflow

Davix H2I handles rendering and file generation. Downstream distribution is handled by the calling application.

Rendering limits #

The /v1/h2i route applies documented limits and validation rules, including:

  • HTML input size checks
  • render width and height controls
  • render pixel-area limits
  • request timeout handling
  • concurrency control
  • quota handling for customer keys

For public-facing documentation, numeric limits should live in your centralized Errors and Limits section instead of being repeated here.

One implementation detail the loaded docs do confirm is that render width and height are clamped to configured ceilings, while pixel-area overflow is rejected.

Example error response #

If a certificate-rendering request fails, the standard API error envelope is returned.

{
  "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 documented standard JSON error structure for external API errors.

Relevant documented errors 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, plus auth and key errors such as invalid_api_key, key_expired, and api_key_location_not_allowed.

Best practices #

Use explicit render dimensions when you need consistent visual output.

Log request_id when present so failed renders can be traced more easily.

Keep one reusable certificate template and change only the dynamic values.

Keep template markup separate from application data logic.

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