Run Tool (Single Execution)

Endpoint #

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

Action #

action=single

Description #

The Run Tool (Single Execution) action executes one analysis tool from the Davix H2I tools system using the H2I engine (PixLab).

This action is part of the public /v1/tools API surface. It accepts one or more uploaded image files, runs exactly one selected tool, and returns structured JSON analysis results. Unlike file-generation endpoints such as /v1/image or /v1/pdf, the /v1/tools endpoint returns JSON analysis payloads.

This action is suitable for workflows such as:

• extracting image metadata
• detecting image format
• checking image dimensions or orientation
• generating hashes
• estimating image quality
• analyzing transparency
• estimating compression efficiency
• comparing images with similarity analysis

Request Format #

Requests to /v1/tools must use:

• Content-Type: multipart/form-data
• API key authentication in request headers
• uploaded source images in the images field
• selected tool provided through tools or tools[]

The route parses tool selections from tools or tools[] as comma-separated text, and action=single requires exactly one tool.

Parameters #

action #

Type: string
Required: Yes
Accepted value: single

Specifies that the request should execute one tool. In single mode, exactly one tool must be selected.

tools #

Type: string
Required: Yes

Defines the selected tool.

The public /v1/tools reference documents these tool names:

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

The external cURL examples also include palette in the implemented tool list. Because the uploaded public source files are inconsistent on this point, do not document palette as a public tool unless you decide to treat the external cURL examples as the controlling public source.

tools[] #

Type: repeated form field
Required: No

Alternative way to provide the selected tool list. The route supports tools or tools[]. In single mode, exactly one tool must be provided.

images #

Type: file[] (multipart/form-data)
Required: Yes

One or more source images used as tool inputs.

• uploaded through the images field
• MIME validated by the upload filter
• some tools work on one image
• some tools, such as similarity, can use multiple uploaded images

Supported Parameters #

The Run Tool (Single Execution) action supports these shared fields:

Parameter	Description
action	Must be single
tools or tools[]	Selected tool name
images	Uploaded source image files

It also supports tool-specific flat form fields depending on the selected tool.

Tool-specific parameters #

includeRawExif #

Used with tools=metadata

Type: boolean or string
Required: No
Default: false

When the value is exactly 'true', raw EXIF data is included in the metadata result.

paletteSize #

Used with tools=colors

Type: integer-like
Required: No
Default: 5
Range: 1..16

Controls palette size for the colors analysis tool.

hashType #

Used with tools=hash

Type: string
Required: No
Default: phash

Supported values:

• phash
• md5
• sha1
• sha256

Unknown values fall back to phash.

similarityMode #

Used with tools=similarity

Type: string
Required: No
Default: pairs

Documented values:

• pairs
• tofirst

Other values fall back to pairs. The route lowercases tool input values during parsing.

similarityThreshold #

Used with tools=similarity

Type: integer-like
Required: No
Default: 8
Range: 0..64

Controls the similarity threshold.

qualitySample #

Used with tools=quality

Type: integer-like
Required: No
Default: 256
Range: 64..512

Controls sampling size for the quality estimate.

transparencySample #

Used with tools=transparency

Type: integer-like
Required: No
Default: 64
Range: 16..128

Controls sampling resolution for transparency analysis.

efficiencyFormat #

Used with tools=efficiency

Type: string
Required: No

Supported values:

• jpeg
• jpg
• png
• webp
• avif

Unsupported values produce unset or null estimate fields in the efficiency helper path.

efficiencyQuality #

Used with tools=efficiency

Type: integer-like
Required: No
Default: 80
Range: 1..100

Controls quality for size-efficiency estimates where applicable.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/tools" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: tools-single-001" \
  -F "action=single" \
  -F "tools=efficiency" \
  -F "images=@/path/to/image.jpg" \
  -F "efficiencyFormat=webp" \
  -F "efficiencyQuality=80"

This example matches the uploaded public external cURL example for single-tool execution with tools=efficiency. It includes the full documented parameter surface relevant to that selected tool:

• action=single
• tools=efficiency
• images
• efficiencyFormat
• efficiencyQuality
• optional idempotency header

Success Response #

Successful /v1/tools requests return JSON analysis results.

The public success shape is documented as:

• { results: [{ originalName, sizeBytes, tools: {...}}], request_id? }

Similarity may add top-level or per-result similarity structures depending on mode.

Use this public-safe example:

{
  "results": [
    {
      "originalName": "image.jpg",
      "sizeBytes": 248221,
      "tools": {
        "efficiency": {}
      }
    }
  ],
  "request_id": "req_abc123"
}

Response Fields #

results[] #

Array of analysis results.

originalName #

Original uploaded filename for the analyzed image.

sizeBytes #

Size of the uploaded image in bytes.

tools #

Object containing tool-specific analysis output keyed by tool name.

request_id #

Request identifier returned by the API when available.

Errors #

The public /v1/tools endpoint uses the same general public error architecture for request validation, uploads, limits, and service availability. Based on the uploaded public source material, the following errors are supported or implied for this route:

• missing_field
• invalid_parameter
• unsupported_media_type
• invalid_upload
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout

Do not document tool_processing_failed unless you have a source file section that explicitly lists it for /v1/tools. The retrieved public /v1/tools reference excerpts provided here do not verify that code.

HTTP Status Codes #

• 400 → invalid request fields or parameters
• 413 → upload limits exceeded
• 415 → unsupported media type
• 429 → rate limit or monthly quota exceeded
• 503 → timeout, rate-limit store unavailable, or server busy

The retrieved public /v1/tools excerpts do not explicitly prove a dedicated 500 tool-processing error code name, so avoid overcommitting to one here unless another uploaded public source explicitly documents it.

Usage Notes #

Idempotency-Key is optional. Both Idempotency-Key and X-Idempotency-Key are accepted.

Use tools or tools[], not tool.

Tool-specific inputs are sent as flat form fields, not inside a nested params object.

action=single requires exactly one tool.

Uploaded files must be valid image files accepted by the endpoint’s upload filter.