Requests and Responses

Davix H2I uses a request–response model.

Applications send HTTP requests to the public API to perform a processing operation, and the platform returns a structured JSON response. Depending on the endpoint and action, that response may contain a generated file URL, a list of generated file URLs, metadata, analysis results, and request tracking information. Processing is handled by the H2I engine (PixLab).

What Is an API Request #

An API request is an HTTP message sent to a Davix H2I public endpoint to perform a specific operation.

Each request includes:

  • an API endpoint
  • authentication credentials
  • request headers
  • either a structured body or multipart file upload content, depending on the route

The public API routes are all POST endpoints under /v1/*.

Request Components #

Endpoint #

The endpoint determines which processing domain handles the request.

Public API endpoints include:

  • /v1/h2i — HTML rendering
  • /v1/image — image processing
  • /v1/pdf — PDF processing
  • /v1/tools — analysis tools

Each endpoint has its own accepted input format, validations, and response shape.

Authentication #

Every public API request must include a valid API key.

Supported authentication methods:

Authorization: Bearer <YOUR_API_KEY>

or

X-Api-Key: <YOUR_API_KEY>

Public API routes require API key authentication before request processing begins.

Headers #

Common request headers include:

Content-Type: application/json
X-Api-Key: <YOUR_API_KEY>
Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>

For multipart endpoints, Content-Type is typically multipart/form-data, generated automatically by the HTTP client when files are attached. Idempotency headers are optional and may be supplied as either Idempotency-Key or X-Idempotency-Key.

Request Body #

The request body contains the operation parameters.

The exact structure depends on the endpoint:

  • /v1/h2i uses JSON or URL-encoded body fields
  • /v1/image uses multipart form fields plus uploaded image files
  • /v1/pdf uses multipart form fields plus uploaded PDF files
  • /v1/tools uses multipart form fields plus uploaded image files

Request Types #

Davix H2I uses two main public request formats.

JSON or URL-Encoded Requests #

Used by:

  • /v1/h2i

This route accepts body fields such as action, html, css, width, height, and PDF-specific rendering options when action=pdf.

Multipart Requests #

Used by:

  • /v1/image
  • /v1/pdf
  • /v1/tools

These routes accept multipart/form-data with uploaded files and additional form parameters. Upload validation, media-type validation, and route-specific action validation are applied before full processing begins.

Example Requests #

JSON Request to /v1/h2i #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: requests-page-h2i-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "image",
    "html": "<div style=\"width:100%;height:100%;display:flex;align-items:center;justify-content:center;font-family:Arial,sans-serif\">Hello from Davix H2I</div>",
    "css": "body{margin:0;background:#ffffff;color:#111111}",
    "width": 1200,
    "height": 630,
    "format": "jpeg"
  }'

This is a valid public render request for /v1/h2i.

Multipart Request to /v1/image #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: requests-page-image-001" \
  -F "action=resize" \
  -F "images=@./input.png" \
  -F "format=jpeg" \
  -F "width=1200" \
  -F "height=630" \
  -F "enlarge=false" \
  -F "quality=90" \
  -F "keepMetadata=false" \
  -F "normalizeOrientation=true" \
  -F "colorSpace=srgb"

This follows the documented multipart model for image-processing requests.

Request Processing Flow #

For public /v1/* routes, the request pipeline follows this general order:

1. Global Middleware #

The platform attaches request metadata, parses optional idempotency headers, applies CORS handling, and runs request body parsing or upload handling as appropriate.

2. Authentication #

The API key is validated.

3. Endpoint Guarding #

The route checks whether the endpoint is allowed for the authenticated caller.

4. Request Controls #

Depending on the route, the platform may apply:

  • timeout middleware
  • upload validation
  • media-type validation
  • daily rate limits
  • customer burst limits
  • quota reservation for customer-key flows
  • concurrency controls

5. Parameter Validation #

The endpoint validates required parameters, allowed actions, media inputs, and route-specific constraints.

6. Processing #

If validation succeeds, the request is executed by the H2I engine (PixLab) or the route’s processing pipeline.

7. Response Generation #

The API returns structured JSON containing either generated file references, metadata, analysis results, or an error object.

What Is an API Response #

An API response is the JSON payload returned after the request is handled.

The exact response depends on the endpoint and action. Davix H2I does not use one single universal success shape for every route. Public responses follow endpoint-specific patterns.

Common Success Response Patterns #

1. Single Generated File #

Some actions return a single output URL:

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

This pattern is used by file-producing actions such as /v1/h2i render operations and some /v1/pdf operations.

2. Multiple Generated Files #

Some actions return a results array:

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/image/<generated-file>?exp=<...>&sig=<...>",
      "format": "jpeg",
      "sizeBytes": 123456,
      "width": 1200,
      "height": 630,
      "quality": 90,
      "originalName": "input.png"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

This pattern is used by many /v1/image actions and some /v1/pdf actions.

3. Metadata or Analysis JSON #

Some actions return structured JSON instead of output-file URLs.

Example categories include:

  • /v1/image with action=metadata
  • /v1/tools analysis operations

These are JSON-first responses and do not follow the same file-download model as render or transformation actions.

Response Fields #

url #

A generated output file URL.

This is returned for file-producing operations such as:

  • /v1/h2i render output
  • /v1/image output files
  • /v1/pdf output files

Output files are served from public static paths such as:

  • /h2i/*
  • /image/*
  • /pdf/*

and are built as signed output URLs when signing is enabled for that output type.

results #

A collection of output objects when an action produces multiple results or per-file results.

request_id #

A request identifier attached by the platform.

It is used for:

  • debugging
  • request tracking
  • support and diagnostics

The platform also exposes the request ID through response handling middleware.

Output Model #

For file-producing endpoints, Davix H2I generally returns URLs to generated files rather than streaming the file directly inside the JSON response.

That means the typical pattern is:

  • the request is processed
  • a file is written to the corresponding output directory
  • a response returns a generated URL
  • the client uses that URL to retrieve the file

This applies to output paths such as /h2i/*, /image/*, and /pdf/*. However, this is not universal across all endpoints. /v1/tools currently returns JSON analysis payloads rather than persisted downloadable output files.

Error Responses #

If a request fails, the API returns a structured error response rather than a success payload.

Common error categories for public routes include:

  • authentication errors
  • missing field errors
  • invalid parameter errors
  • unsupported media type errors
  • upload limit errors
  • rate-limit or quota errors
  • timeout and processing errors

The exact error code depends on the route and failure condition.

Example categories confirmed in the public API include:

  • invalid_api_key
  • missing_field
  • invalid_parameter
  • unsupported_media_type
  • rate_limit_exceeded
  • monthly_quota_exceeded
  • timeout
  • route-specific processing failures such as html_render_failed, image_processing_failed, and pdf_tool_failed

Successful vs Failed Requests #

Successful Request #

A successful request may result in:

  • a single output URL
  • multiple output URLs
  • metadata JSON
  • analysis JSON

Failed Request #

A failed request returns structured error information and no success payload for the requested operation. Depending on the route, processing may stop before heavy work begins if authentication, validation, upload checks, or limits fail.

Using Responses in Applications #

Applications commonly use responses in one of these ways:

  • store generated file URLs
  • fetch and display generated outputs
  • pass output URLs into downstream systems
  • read structured metadata or analysis data
  • trigger follow-up workflows based on the response payload

Because the response format depends on the endpoint and action, applications should parse responses according to the specific API operation they are calling.

Summary #

Davix H2I uses a structured public request–response model.

Clients send authenticated requests to /v1/* endpoints using either JSON/URL-encoded bodies or multipart form uploads, depending on the route. After authentication, validation, and route-specific processing, the API returns structured JSON. For file-producing operations, this usually includes a generated output URL or results[] collection. For analysis and metadata operations, the API may return JSON-only results instead. All processing is handled through the H2I engine (PixLab) and the surrounding public route pipeline.

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