Parameters and Payloads

When interacting with the Davix H2I public API, each request includes parameters that describe the operation to perform.

These parameters are sent in the request payload and control:

• which action to run
• what input to process
• how the output should be generated
• which optional processing settings should be applied

Parameters are interpreted by the public API and passed into the H2I engine (PixLab) through the endpoint-specific processing pipeline.

What Are Parameters #

Parameters are the individual request values that define a processing operation.

Depending on the endpoint, parameters can include:

• operation type
• HTML input
• uploaded files
• output format
• dimensions
• processing options
• action-specific settings

Each public endpoint accepts its own parameter set. There is no single shared parameter list for every route.

What Is a Payload #

The payload is the body of the HTTP request that carries the request parameters.

In Davix H2I, public payloads are sent in one of these formats:

• JSON
• URL-encoded form fields
• multipart form-data

The format depends on the endpoint being called.

Request Types #

Davix H2I uses two main public payload styles.

Structured Body Payloads #

Used by:

• /v1/h2i

This endpoint accepts structured body fields in either:

• application/json
• URL-encoded form format

Typical fields include action, html, optional css, output dimensions, and PDF-specific rendering options when action=pdf.

Multipart Payloads #

Used by:

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

These routes use multipart/form-data so the request can include uploaded files together with form parameters.

JSON or URL-Encoded Payloads #

For /v1/h2i, the payload contains rendering parameters directly in the request body.

Example:

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

Verified public /v1/h2i fields include:

• action
• html
• css
• width
• height
• format
• pdfFormat
• pdfLandscape
• pdfMargin
• preferCSSPageSize
• scale
• printMode
• printBackground

Not all of these fields apply to every action. For example, format applies to image rendering, while the PDF-specific fields apply when action=pdf.

Multipart Payloads #

For upload endpoints, the payload is sent as multipart/form-data.

This format allows the request to include both uploaded files and regular form fields.

/v1/image #

/v1/image uses multipart payloads with image files and action-specific parameters. Supported public actions include:

• format
• resize
• crop
• transform
• compress
• enhance
• padding
• frame
• background
• watermark
• pdf
• metadata
• multitask

Example:

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: parameters-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"

/v1/pdf #

/v1/pdf also uses multipart payloads with uploaded PDF files and action-specific fields.

Example:

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: parameters-pdf-001" \
  -F "action=split" \
  -F "files=@./document.pdf" \
  -F "ranges=1-2,3-5" \
  -F "prefix=chapter_"

/v1/tools #

/v1/tools uses multipart payloads for uploaded image files plus tool-selection fields.

Example:

curl -sS -X POST "https://pixlab.davix.dev/v1/tools" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: parameters-tools-001" \
  -F "action=multitask" \
  -F "tools=metadata,dimensions,hash,similarity,quality" \
  -F "images=@./samples/a.jpg" \
  -F "images=@./samples/b.jpg" \
  -F "hashType=phash" \
  -F "similarityMode=toFirst" \
  -F "similarityThreshold=10" \
  -F "qualitySample=256"

This is important because /v1/tools is part of the public API and should be included in the payload model.

Required vs Optional Parameters #

Required Parameters #

Some parameters must be present for a request to be valid.

Examples:

• /v1/h2i requires action and html
• /v1/image requires action and uploaded images
• /v1/pdf requires action and uploaded files
• /v1/tools requires action, uploaded images, and tool selection fields such as tools or tools[]

Missing required fields are rejected with structured API errors such as missing_field or other route-specific validation errors.

Optional Parameters #

Optional parameters modify the processing behavior.

Examples include:

• output format
• width and height
• rendering settings
• compression settings
• naming prefixes
• tool-specific analysis options

Optional parameters vary by endpoint and by action. A parameter that is valid for one route or action may be ignored or rejected on another.

Passing Content to the API #

The API accepts different kinds of content depending on the endpoint.

HTML Content #

For /v1/h2i, content is provided directly in body fields such as html and optional css. This is used for HTML-to-image and HTML-to-PDF rendering.

File Uploads #

For /v1/image, /v1/pdf, and /v1/tools, content is sent as uploaded files in multipart form-data.

Public endpoint file expectations include:

• /v1/image — image files
• /v1/pdf — PDF files, with some action-specific support for additional file fields such as image-based watermark input
• /v1/tools — image files

These upload routes apply route-specific MIME and validation checks before processing.

Payload Processing #

When a request is received, the platform processes the payload in several stages:

1. Payload Parsing #

The request body is parsed according to its content type.

2. Parameter Extraction #

The endpoint extracts fields and files from the request.

3. Validation #

Required fields, accepted values, data formats, and route-specific constraints are checked.

4. Limit Enforcement #

The route may apply upload, size, dimension, page, rate, quota, timeout, or concurrency limits depending on the endpoint.

5. Processing #

If validation succeeds, the request is executed through the H2I engine (PixLab) and the route-specific processing layer.

Invalid, missing, or unsupported parameters result in structured API errors instead of processing.

Structuring Payloads Correctly #

To ensure successful requests:

• use JSON or URL-encoded body fields for /v1/h2i
• use multipart/form-data for /v1/image, /v1/pdf, and /v1/tools
• include all required parameters for the selected endpoint and action
• use the correct field names and data types
• upload files only to the routes that accept multipart payloads
• avoid undocumented fields or unsupported values

These rules reflect the public route model implemented by the current API.

Example Workflow #

A common /v1/h2i workflow looks like this:

1. your application generates HTML
2. it builds a structured body payload
3. it sends the authenticated request to /v1/h2i
4. the platform validates and processes the payload
5. the API returns a structured response

Depending on the endpoint and action, that response may contain a generated file URL, a list of result objects, or structured JSON data. It is not always a single output URL.

Summary #

Parameters define how a Davix H2I request should be processed, and payloads carry those parameters to the API.

• /v1/h2i uses structured body fields in JSON or URL-encoded form
• /v1/image, /v1/pdf, and /v1/tools use multipart form-data
• required parameters depend on the endpoint and selected action
• optional parameters allow route-specific customization

All public parameters are interpreted through the public API pipeline and then processed by the H2I engine (PixLab).