curl Examples

This page shows complete cURL examples for the external Davix H2I API.

Requests are processed by the H2I engine (PixLab) through the public external endpoints:

/v1/h2i
/v1/image
/v1/pdf
/v1/tools

External requests require API key authentication. Supported authentication methods are:

X-Api-Key
Authorization: Bearer <key>

Optional idempotency headers are also supported:

Idempotency-Key
X-Idempotency-Key

In production environments, API keys must be sent in headers. Body and query-string API key transport is rejected.

Setup #

BASE="https://pixlab.davix.dev"
API_KEY="<YOUR_API_KEY>"

Authentication #

Use either of these patterns:

-H "X-Api-Key: $API_KEY"

-H "Authorization: Bearer $API_KEY"

Optional idempotency:

-H "Idempotency-Key: your-request-id-001"

Valid idempotency keys:

length: 8 to 128
allowed characters: A-Z, a-z, 0-9, ., _, :, -

A valid key is echoed back by the server as the Idempotency-Key response header.

Notes about outputs #

/v1/h2i, /v1/image, and /v1/pdf return generated outputs and signed URLs.
/v1/tools returns structured JSON analysis results instead of generated file URLs.
Static output fetches for /h2i/*, /image/*, and /pdf/* are behind signed URL protection. /tools/* is signed when signed output mode is enabled.

Endpoint #

POST /v1/h2i

Supported actions:

image
pdf

Action #

action=image

Converts HTML into an image.

curl -sS -X POST "$BASE/v1/h2i" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: h2i-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\">Hello</div>",
    "css": "body{margin:0}",
    "width": 1200,
    "height": 1600,
    "format": "jpeg"
  }'

Parameters

action — required, must be image
html — required HTML string
css — optional CSS string
width — optional viewport width, default 1000
height — optional viewport height, default 1500
format — optional output format, default png; only jpeg produces JPEG, other values become PNG

Notes

If width * height exceeds the render pixel limit, the request fails with render_size_exceeded.

Action #

action=pdf

Converts HTML into a PDF.

curl -sS -X POST "$BASE/v1/h2i" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "pdf",
    "html": "<h1>Invoice</h1>",
    "css": "body{font-family:sans-serif}",
    "width": 1000,
    "height": 1500,
    "pdfFormat": "LETTER",
    "pdfLandscape": false,
    "pdfMargin": 24,
    "preferCSSPageSize": true,
    "scale": 1,
    "printMode": false,
    "printBackground": true
  }'

Parameters

action — required, must be pdf
html — required HTML string
css — optional CSS string
width, height — optional viewport values
pdfFormat — optional, default A4; only LETTER maps to Letter
pdfLandscape — optional boolean, default false
pdfMargin — optional integer, default 24
preferCSSPageSize — optional boolean, default true
scale — optional numeric, default 1
printMode — optional boolean, default false
printBackground — optional boolean, default true

Endpoint #

POST /v1/image

Supported actions:

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

The endpoint uses multipart/form-data.

Shared image parameters #

action
images
watermarkImage
format
width, height, enlarge
cropX, cropY, cropWidth, cropHeight
rotate, flipH, flipV
targetSizeKB, quality
keepMetadata, normalizeOrientation
blur, sharpen, grayscale, sepia
brightness, contrast, saturation
pad, padTop, padRight, padBottom, padLeft, padColor
border, borderColor, borderRadius
backgroundColor, backgroundBlur
watermarkText, watermarkFontSize, watermarkColor, watermarkOpacity, watermarkPosition, watermarkMargin, watermarkScale
pdfMode, pdfPageSize, pdfOrientation, pdfMargin, pdfEmbedFormat, pdfJpegQuality
colorSpace
includeRawExif

Action #

action=format

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-002" \
  -F "action=format" \
  -F "images=@./samples/a.jpg" \
  -F "format=webp"

Action #

action=resize

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-003" \
  -F "action=resize" \
  -F "images=@./samples/a.jpg" \
  -F "width=1024" \
  -F "height=768"

Action #

action=crop

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-004" \
  -F "action=crop" \
  -F "images=@./samples/a.jpg" \
  -F "cropX=0" \
  -F "cropY=0" \
  -F "cropWidth=800" \
  -F "cropHeight=600"

Action #

action=transform

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-005" \
  -F "action=transform" \
  -F "images=@./samples/a.jpg" \
  -F "rotate=90" \
  -F "flipH=true"

Action #

action=compress

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-006" \
  -F "action=compress" \
  -F "images=@./samples/a.jpg" \
  -F "targetSizeKB=200" \
  -F "quality=80"

Action #

action=enhance

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-007" \
  -F "action=enhance" \
  -F "images=@./samples/a.jpg" \
  -F "sharpen=1" \
  -F "contrast=1.1"

Action #

action=padding

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-008" \
  -F "action=padding" \
  -F "images=@./samples/a.jpg" \
  -F "pad=20" \
  -F "padColor=#ffffff"

Action #

action=frame

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-009" \
  -F "action=frame" \
  -F "images=@./samples/a.jpg" \
  -F "border=4" \
  -F "borderColor=#000000"

Action #

action=background

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-010" \
  -F "action=background" \
  -F "images=@./samples/a.png" \
  -F "backgroundColor=#ffffff"

Action #

action=watermark

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-011" \
  -F "action=watermark" \
  -F "images=@./samples/a.jpg" \
  -F "watermarkText=H2I"

Action #

action=pdf

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-012" \
  -F "action=pdf" \
  -F "images=@./samples/a.jpg" \
  -F "format=pdf" \
  -F "pdfMode=single"

Action #

action=metadata

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-013" \
  -F "action=metadata" \
  -F "images=@./samples/a.jpg" \
  -F "normalizeOrientation=true" \
  -F "includeRawExif=true"

Action #

action=multitask

curl -sS -X POST "$BASE/v1/image" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-014" \
  -F "action=multitask" \
  -F "images=@./samples/a.jpg" \
  -F "width=1200" \
  -F "format=webp" \
  -F "watermarkText=H2I"

Any applicable shared image transformation fields may be combined in one request for action=multitask.

Endpoint #

POST /v1/pdf

Supported actions:

merge
to-images
compress
extract-images
watermark
rotate
metadata
reorder
delete-pages
extract
flatten
encrypt
decrypt
split

The endpoint uses multipart/form-data. One optional watermarkImage upload is accepted, and for non-merge actions the first uploaded PDF is used as the primary input.

Shared PDF parameters #

action
files
sortByName
pages
format
quality
density
watermarkText
watermarkImage
opacity
position
fontSize
color
x
y
degrees
order
password
userPassword
ownerPassword
ranges
prefix

Action #

action=merge

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-015" \
  -F "action=merge" \
  -F "files=@./samples/one.pdf" \
  -F "files=@./samples/two.pdf" \
  -F "sortByName=true"

Action #

action=to-images

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-016" \
  -F "action=to-images" \
  -F "files=@./samples/doc.pdf" \
  -F "pages=all" \
  -F "format=png" \
  -F "density=144" \
  -F "quality=85"

Action #

action=compress

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-017" \
  -F "action=compress" \
  -F "files=@./samples/doc.pdf"

Action #

action=extract-images

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-018" \
  -F "action=extract-images" \
  -F "files=@./samples/doc.pdf" \
  -F "pages=all" \
  -F "imageFormat=jpeg"

Action #

action=watermark

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-019" \
  -F "action=watermark" \
  -F "files=@./samples/doc.pdf" \
  -F "watermarkText=CONFIDENTIAL" \
  -F "opacity=0.3" \
  -F "position=center"

Action #

action=rotate

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-020" \
  -F "action=rotate" \
  -F "files=@./samples/doc.pdf" \
  -F "degrees=90" \
  -F "pages=1,2"

Action #

action=metadata

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-021" \
  -F "action=metadata" \
  -F "files=@./samples/doc.pdf" \
  -F "title=Updated"

Action #

action=reorder

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-022" \
  -F "action=reorder" \
  -F "files=@./samples/doc.pdf" \
  -F "order=3,1,2"

Action #

action=delete-pages

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-023" \
  -F "action=delete-pages" \
  -F "files=@./samples/doc.pdf" \
  -F "pages=2,4"

Action #

action=extract

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-024" \
  -F "action=extract" \
  -F "files=@./samples/doc.pdf" \
  -F "pages=1-3"

Action #

action=flatten

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-025" \
  -F "action=flatten" \
  -F "files=@./samples/doc.pdf"

Action #

action=encrypt

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-026" \
  -F "action=encrypt" \
  -F "files=@./samples/doc.pdf" \
  -F "userPassword=userpass" \
  -F "ownerPassword=ownerpass"

userPassword is required for encrypt. ownerPassword is optional and defaults to userPassword if omitted. Encryption depends on qpdf being available in the runtime environment.

Action #

action=decrypt

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-027" \
  -F "action=decrypt" \
  -F "files=@./samples/locked.pdf" \
  -F "password=userpass"

Action #

action=split

curl -sS -X POST "$BASE/v1/pdf" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-028" \
  -F "action=split" \
  -F "files=@./samples/doc.pdf" \
  -F "ranges=1-2,3-5" \
  -F "prefix=chapter_"

For PDF requests:

pages accepts selectors such as all, first, and CSV page ranges
order is used for page reorder
ranges is required for split
password is required for decrypt
userPassword is required for encrypt

Endpoint #

POST /v1/tools

Top-level actions:

single
multitask

Actual tool selection is controlled through tools or tools[].

Documented tool names:

metadata
colors
detect-format
orientation
hash
similarity
dimensions
quality
transparency
efficiency

Shared tools parameters #

action
images
tools or tools[]
includeRawExif
paletteSize
hashType
qualitySample
transparencySample
similarityMode
similarityThreshold
efficiencyFormat
efficiencyQuality

Tool #

metadata

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-029" \
  -F "action=single" \
  -F "tools=metadata" \
  -F "images=@./samples/a.jpg" \
  -F "includeRawExif=true"

Tool #

colors

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-030" \
  -F "action=single" \
  -F "tools=colors" \
  -F "images=@./samples/a.jpg" \
  -F "paletteSize=8"

Tool #

detect-format

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-031" \
  -F "action=single" \
  -F "tools=detect-format" \
  -F "images=@./samples/a.jpg"

Tool #

orientation

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-032" \
  -F "action=single" \
  -F "tools=orientation" \
  -F "images=@./samples/a.jpg"

Tool #

hash

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-033" \
  -F "action=single" \
  -F "tools=hash" \
  -F "images=@./samples/a.jpg" \
  -F "hashType=phash"

Tool #

similarity

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-034" \
  -F "action=single" \
  -F "tools=similarity" \
  -F "images=@./samples/a.jpg" \
  -F "images=@./samples/b.jpg" \
  -F "similarityMode=tofirst" \
  -F "similarityThreshold=8"

Tool #

dimensions

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-035" \
  -F "action=single" \
  -F "tools=dimensions" \
  -F "images=@./samples/a.jpg"

Tool #

transparency

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-036" \
  -F "action=single" \
  -F "tools=transparency" \
  -F "images=@./samples/a.png" \
  -F "transparencySample=64"

Tool #

quality

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-037" \
  -F "action=single" \
  -F "tools=quality" \
  -F "images=@./samples/a.jpg" \
  -F "qualitySample=256"

Tool #

efficiency

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-038" \
  -F "action=single" \
  -F "tools=efficiency" \
  -F "images=@./samples/a.jpg" \
  -F "efficiencyFormat=webp" \
  -F "efficiencyQuality=80"

Action #

action=multitask

curl -sS -X POST "$BASE/v1/tools" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: idem-ext-039" \
  -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"

Notes

action=single requires exactly one tool.
tools and tools[] are both accepted.
tools input is parsed as a lowercase comma-separated list.
similarityMode supports pairs and tofirst.
Multitask is flat multipart form-data. There is no nested tasks[] JSON structure in the documented implementation.

Common external errors #

Common external error codes relevant to cURL usage include:

api_key_location_not_allowed
invalid_api_key
key_expired
endpoint_not_allowed
rate_limit_exceeded
rate_limit_store_unavailable
timeout
server_busy
file_too_large
too_many_files
total_upload_exceeded
dimension_exceeded
invalid_upload
unsupported_media_type
monthly_quota_exceeded
invalid_parameter
missing_field
html_too_large
render_size_exceeded
html_render_failed
image_processing_failed
pdf_tool_failed
tool_processing_failed

Final notes #

/v1/h2i uses JSON request bodies.
/v1/image, /v1/pdf, and /v1/tools use multipart/form-data.
/v1/tools returns structured JSON analysis results rather than generated file URLs.
encrypt and decrypt depend on qpdf being available in the runtime environment.
Generated output URLs are signed and protected for output-fetch paths according to the configured signed URL behavior.

Still stuck? How can we help?

curl Examples

Setup #

Authentication #

Notes about outputs #

Endpoint #

Action #

Action #

Endpoint #

Shared image parameters #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Endpoint #

Shared PDF parameters #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Action #

Endpoint #

Shared tools parameters #

Tool #

Tool #

Tool #

Tool #

Tool #

Tool #

Tool #

Tool #

Tool #

Tool #

Action #

Common external errors #

Final notes #

How can we help?

Was it helpful ?

Share This Article :