Convert Image to PDF

Endpoint #

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

Action #

action=pdf

Description #

The Convert Image to PDF action converts one or more uploaded image files into PDF output using the H2I engine (PixLab) image processing pipeline.

This action is useful when image-based content must be produced in document format for reporting, archiving, sharing, or downstream document workflows. The uploaded image is processed by the backend infrastructure that powers Davix H2I, and the generated output is returned as a file URL in the API response.

Request Format #

Requests to /v1/image must use multipart/form-data because image files are uploaded with the request. The source file is sent through the images field together with PDF conversion parameters.

Parameters #

action #

Type: string
Required: Yes
Accepted value: pdf

Specifies that the request should convert the uploaded image into PDF output.

images #

Type: file[]
Required: Yes

One or more source image files to convert. The /v1/image route accepts image uploads through the images field.

pdfMode #

Type: string
Required: No
Default: single

Accepted values:

• single
• multi

Only the exact value multi enables multi-page PDF output.

pdfPageSize #

Type: string
Required: No
Default: auto

Accepted values:

• auto
• a4
• letter

Unknown values fall back to auto.

pdfOrientation #

Type: string
Required: No
Default: portrait

Accepted values:

• portrait
• landscape

Unknown values fall back to portrait.

pdfMargin #

Type: integer
Required: No
Default: 0

Controls PDF drawing margin. Parsed with integer conversion in the route pipeline.

pdfEmbedFormat #

Type: string
Required: No
Default: png

Accepted values:

• png
• jpeg
• jpg

jpg is normalized to jpeg. Invalid values fall back to png.

pdfJpegQuality #

Type: integer
Required: No
Default: 85

Range:

• 20 to 100

Used for JPEG quality when embedding images into the generated PDF.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-pdf-001" \
  -F "action=pdf" \
  -F "images=@./samples/a.jpg" \
  -F "pdfMode=single" \
  -F "pdfPageSize=a4" \
  -F "pdfOrientation=portrait" \
  -F "pdfMargin=0" \
  -F "pdfEmbedFormat=jpeg" \
  -F "pdfJpegQuality=85"

This example uses the documented PDF conversion fields for the /v1/image pdf action.

Success Response #

Successful requests return HTTP 200 and a JSON body with the generated output.

Example #

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/image/<generated-file>?exp=<...>&sig=<...>",
      "format": "pdf",
      "sizeBytes": 123456,
      "width": 1200,
      "height": 800,
      "quality": 85,
      "originalName": "a.jpg"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

For non-metadata /v1/image actions, the documented success shape is results[] with url, format, sizeBytes, width, height, quality, and originalName, plus optional request_id.

Response Fields #

• results[] → array of generated outputs
• url → output file URL
• format → output format
• sizeBytes → output file size
• width / height → output dimensions
• originalName → original uploaded filename
• request_id → request identifier

Errors #

The /v1/image endpoint may return these errors during image-to-PDF conversion:

• invalid_parameter
• missing_field
• unsupported_media_type
• invalid_upload
• too_many_files
• total_upload_exceeded
• dimension_exceeded
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout
• image_processing_failed

Authentication and idempotency errors can also occur.

HTTP Status Codes #

• 400 → invalid request
• 413 → upload limits exceeded
• 415 → unsupported media type
• 429 → rate limit or quota exceeded
• 503 → timeout or server busy
• 500 → processing error

Usage Notes #

Generated URLs should not be treated as permanent storage. Store important outputs externally for long-term retention.

Idempotency-Key is optional and supported for /v1/* requests. X-Idempotency-Key is also accepted, and a valid key is echoed back in the Idempotency-Key response header.

/v1/image accepts image uploads through multipart/form-data and returns generated output URLs.

In production, API keys must be sent in headers, not in the request body or query string.