PHP Examples

This page shows complete PHP 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 #

These examples use PHP with the built-in cURL extension.

<?php
$BASE = 'https://pixlab.davix.dev';
$API_KEY = '<YOUR_API_KEY>';

Authentication #

Use either of these patterns:

[
    "X-Api-Key: {$API_KEY}",
]

[
    "Authorization: Bearer {$API_KEY}",
]

Optional idempotency #

All examples may also include:

"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. Invalid values return invalid_idempotency_key.

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.

Helper functions #

These helpers are used by the examples below.

<?php
function apiJsonRequest(string $url, array $payload, array $headers = []): array
{
    $ch = curl_init($url);    $baseHeaders = array_merge([
        'Content-Type: application/json',
    ], $headers);    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $baseHeaders,
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
    ]);    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);    return [
        'status' => $status,
        'data' => json_decode($response, true),
        'raw' => $response,
    ];
}function apiMultipartRequest(string $url, array $parts, array $headers = []): array
{
    $boundary = '--------------------------' . bin2hex(random_bytes(12));
    $body = '';    foreach ($parts as $part) {
        $body .= "--{$boundary}\r\n";
        $body .= 'Content-Disposition: form-data; name="' . $part['name'] . '"';        if (isset($part['filename'])) {
            $body .= '; filename="' . $part['filename'] . '"' . "\r\n";
            $body .= 'Content-Type: ' . ($part['type'] ?? 'application/octet-stream') . "\r\n\r\n";
            $body .= file_get_contents($part['path']) . "\r\n";
        } else {
            $body .= "\r\n\r\n" . $part['value'] . "\r\n";
        }
    }    $body .= "--{$boundary}--\r\n";    $baseHeaders = array_merge([
        "Content-Type: multipart/form-data; boundary={$boundary}",
        'Content-Length: ' . strlen($body),
    ], $headers);    $ch = curl_init($url);    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $baseHeaders,
        CURLOPT_POSTFIELDS => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
    ]);    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);    return [
        'status' => $status,
        'data' => json_decode($response, true),
        'raw' => $response,
    ];
}

Endpoint #

POST /v1/h2i

Supported actions:

image
pdf

Action #

action=image

Converts HTML into an image.

<?php
$response = apiJsonRequest(
    "{$BASE}/v1/h2i",
    [
        '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',
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: h2i-image-001',
    ]
);print_r($response['data']);

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-size guard, the request fails with render_size_exceeded.

Action #

action=pdf

Converts HTML into a PDF.

<?php
$response = apiJsonRequest(
    "{$BASE}/v1/h2i",
    [
        '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,
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-001',
    ]
);print_r($response['data']);

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 #

These parameters are reused across image actions:

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

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'format'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'format', 'value' => 'webp'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-002',
    ]
);print_r($response['data']);

Action #

action=resize

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'resize'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'width', 'value' => '1024'],
        ['name' => 'height', 'value' => '768'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-003',
    ]
);print_r($response['data']);

Action #

action=crop

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'crop'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'cropX', 'value' => '0'],
        ['name' => 'cropY', 'value' => '0'],
        ['name' => 'cropWidth', 'value' => '800'],
        ['name' => 'cropHeight', 'value' => '600'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-004',
    ]
);print_r($response['data']);

Action #

action=transform

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'transform'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'rotate', 'value' => '90'],
        ['name' => 'flipH', 'value' => 'true'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-005',
    ]
);print_r($response['data']);

Action #

action=compress

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'compress'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'targetSizeKB', 'value' => '200'],
        ['name' => 'quality', 'value' => '80'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-006',
    ]
);print_r($response['data']);

Action #

action=enhance

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'enhance'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'sharpen', 'value' => '1'],
        ['name' => 'contrast', 'value' => '1.1'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-007',
    ]
);print_r($response['data']);

Action #

action=padding

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'padding'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'pad', 'value' => '20'],
        ['name' => 'padColor', 'value' => '#ffffff'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-008',
    ]
);print_r($response['data']);

Action #

action=frame

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'frame'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'border', 'value' => '4'],
        ['name' => 'borderColor', 'value' => '#000000'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-009',
    ]
);print_r($response['data']);

Action #

action=background

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'background'],
        ['name' => 'images', 'path' => './samples/a.png', 'filename' => 'a.png', 'type' => 'image/png'],
        ['name' => 'backgroundColor', 'value' => '#ffffff'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-010',
    ]
);print_r($response['data']);

Action #

action=watermark

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'watermark'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'watermarkText', 'value' => 'H2I'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-011',
    ]
);print_r($response['data']);

Action #

action=pdf

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'pdf'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'format', 'value' => 'pdf'],
        ['name' => 'pdfMode', 'value' => 'single'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-012',
    ]
);print_r($response['data']);

Action #

action=metadata

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'metadata'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'normalizeOrientation', 'value' => 'true'],
        ['name' => 'includeRawExif', 'value' => 'true'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-013',
    ]
);print_r($response['data']);

Action #

action=multitask

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/image",
    [
        ['name' => 'action', 'value' => 'multitask'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'width', 'value' => '1200'],
        ['name' => 'format', 'value' => 'webp'],
        ['name' => 'watermarkText', 'value' => 'H2I'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-014',
    ]
);print_r($response['data']);

For /v1/image:

metadata returns JSON metadata results.
other actions return generated-file results with signed URLs.

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

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'merge'],
        ['name' => 'files', 'path' => './samples/one.pdf', 'filename' => 'one.pdf', 'type' => 'application/pdf'],
        ['name' => 'files', 'path' => './samples/two.pdf', 'filename' => 'two.pdf', 'type' => 'application/pdf'],
        ['name' => 'sortByName', 'value' => 'true'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-015',
    ]
);print_r($response['data']);

Action #

action=to-images

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'to-images'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'pages', 'value' => 'all'],
        ['name' => 'format', 'value' => 'png'],
        ['name' => 'density', 'value' => '144'],
        ['name' => 'quality', 'value' => '85'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-016',
    ]
);print_r($response['data']);

Action #

action=compress

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'compress'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-017',
    ]
);print_r($response['data']);

Action #

action=extract-images

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'extract-images'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'pages', 'value' => 'all'],
        ['name' => 'imageFormat', 'value' => 'jpeg'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-018',
    ]
);print_r($response['data']);

Action #

action=watermark

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'watermark'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'watermarkText', 'value' => 'CONFIDENTIAL'],
        ['name' => 'opacity', 'value' => '0.3'],
        ['name' => 'position', 'value' => 'center'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-019',
    ]
);print_r($response['data']);

Action #

action=rotate

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'rotate'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'degrees', 'value' => '90'],
        ['name' => 'pages', 'value' => '1,2'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-020',
    ]
);print_r($response['data']);

Action #

action=metadata

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'metadata'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'title', 'value' => 'Updated'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-021',
    ]
);print_r($response['data']);

Action #

action=reorder

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'reorder'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'order', 'value' => '[3,1,2]'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-022',
    ]
);print_r($response['data']);

Action #

action=delete-pages

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'delete-pages'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'pages', 'value' => '2-4'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-023',
    ]
);print_r($response['data']);

Action #

action=extract

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'extract'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'pages', 'value' => '1-3'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-024',
    ]
);print_r($response['data']);

Action #

action=flatten

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'flatten'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-025',
    ]
);print_r($response['data']);

Action #

action=encrypt

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'encrypt'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'userPassword', 'value' => 'userpass'],
        ['name' => 'ownerPassword', 'value' => 'ownerpass'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-026',
    ]
);print_r($response['data']);

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

Action #

action=decrypt

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'decrypt'],
        ['name' => 'files', 'path' => './samples/locked.pdf', 'filename' => 'locked.pdf', 'type' => 'application/pdf'],
        ['name' => 'password', 'value' => 'userpass'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-027',
    ]
);print_r($response['data']);

Action #

action=split

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/pdf",
    [
        ['name' => 'action', 'value' => 'split'],
        ['name' => 'files', 'path' => './samples/doc.pdf', 'filename' => 'doc.pdf', 'type' => 'application/pdf'],
        ['name' => 'ranges', 'value' => '1-2,3-5'],
        ['name' => 'prefix', 'value' => 'chapter_'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-028',
    ]
);print_r($response['data']);

For /v1/pdf:

pages accepts selectors such as all, first, and CSV page ranges
ranges is required for split
password is required for decrypt
userPassword is required for encrypt
page-limited operations can return pdf_page_limit_exceeded

Endpoint #

POST /v1/tools

Top-level action values are single and multitask, but analyzer 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

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'metadata'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'includeRawExif', 'value' => 'true'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-029',
    ]
);print_r($response['data']);

Tool #

colors

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'colors'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'paletteSize', 'value' => '8'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-030',
    ]
);print_r($response['data']);

Tool #

detect-format

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'detect-format'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-031',
    ]
);print_r($response['data']);

Tool #

orientation

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'orientation'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-032',
    ]
);print_r($response['data']);

Tool #

hash

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'hash'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'hashType', 'value' => 'phash'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-033',
    ]
);print_r($response['data']);

Tool #

similarity

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'similarity'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'images', 'path' => './samples/b.jpg', 'filename' => 'b.jpg', 'type' => 'image/jpeg'],
        ['name' => 'similarityMode', 'value' => 'tofirst'],
        ['name' => 'similarityThreshold', 'value' => '8'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-034',
    ]
);print_r($response['data']);

Tool #

dimensions

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'dimensions'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-035',
    ]
);print_r($response['data']);

Tool #

transparency

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'transparency'],
        ['name' => 'images', 'path' => './samples/a.png', 'filename' => 'a.png', 'type' => 'image/png'],
        ['name' => 'transparencySample', 'value' => '64'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-036',
    ]
);print_r($response['data']);

Tool #

quality

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'quality'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'qualitySample', 'value' => '256'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-037',
    ]
);print_r($response['data']);

Tool #

efficiency

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'single'],
        ['name' => 'tools', 'value' => 'efficiency'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'efficiencyFormat', 'value' => 'webp'],
        ['name' => 'efficiencyQuality', 'value' => '80'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-038',
    ]
);print_r($response['data']);

Action #

action=multitask

<?php
$response = apiMultipartRequest(
    "{$BASE}/v1/tools",
    [
        ['name' => 'action', 'value' => 'multitask'],
        ['name' => 'tools', 'value' => 'metadata,dimensions,hash,similarity,quality'],
        ['name' => 'images', 'path' => './samples/a.jpg', 'filename' => 'a.jpg', 'type' => 'image/jpeg'],
        ['name' => 'images', 'path' => './samples/b.jpg', 'filename' => 'b.jpg', 'type' => 'image/jpeg'],
        ['name' => 'hashType', 'value' => 'phash'],
        ['name' => 'similarityMode', 'value' => 'tofirst'],
        ['name' => 'similarityThreshold', 'value' => '10'],
        ['name' => 'qualitySample', 'value' => '256'],
    ],
    [
        "X-Api-Key: {$API_KEY}",
        'Idempotency-Key: idem-ext-039',
    ]
);print_r($response['data']);

Notes

action=single requires exactly one tool.
tools and tools[] are both accepted.
similarityMode supports pairs and tofirst.
The multitask request format is flat multipart form-data. There is no nested tasks[] JSON structure in the documented implementation.

Tools response shape #

/v1/tools returns structured analysis results in this form:

[
    'results' => [
        [
            'originalName' => 'a.jpg',
            'sizeBytes' => 123456,
            'tools' => [],
        ],
    ],
    'request_id' => 'req_abc123',
]

Similarity can also add similarity-specific structures depending on mode.

Common external errors #

These are the main external error codes relevant to PHP usage:

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 bodies.
/v1/image, /v1/pdf, and /v1/tools use multipart/form-data.
/v1/tools returns 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?

PHP Examples

Setup #

Authentication #

Optional idempotency #

Notes about outputs #

Helper functions #

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 #

Tools response shape #

Common external errors #

Final notes #

How can we help?

Was it helpful ?

Share This Article :