Run Multiple Tools (Multitask)

Endpoint #

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

Action #

action=multitask

Description #

The Run Multiple Tools (Multitask) action executes multiple tools in a single request using the H2I engine (PixLab).

This action is part of the public /v1/tools API surface. It allows applications to upload one or more images, request multiple analysis tools in one request, and receive structured JSON results in a single response. 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 metadata
• checking dimensions and orientation
• detecting format
• analyzing quality or transparency
• generating hashes
• running similarity analysis across uploaded images

Request Format #

Requests to /v1/tools must use:

• Content-Type: multipart/form-data
• API key authentication in request headers
• one or more uploaded image files in the images field
• multiple tool names provided through tools or tools[]

The multitask request structure is flat multipart form-data. There is no nested tasks[] JSON payload structure.

Parameters #

action #

Type: string
Required: Yes
Accepted value: multitask

Specifies that the request should execute multiple tools in one request.

tools #

Type: string
Required: Yes

Defines the tools to execute.

This field can contain:

• a comma-separated list of tool names
• or a single value

The public external API reference documents these tool names:

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

The external cURL example file also lists palette in the implemented tool set. Because the uploaded public sources are inconsistent on that point, this page should follow the external API reference list above for public documentation.

tools[] #

Type: repeated form field
Required: No

Alternative way to provide multiple tool names.

Each tools[] field represents one tool to execute. This is useful when building multipart requests programmatically. The route supports either tools or tools[].

images #

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

One or more source images used as input for the selected tools.

• uploaded through the images field
• MIME-validated
• the same uploaded images are used across all requested tools
• some tools become more useful when multiple images are uploaded, such as similarity analysis

Supported Parameters #

The Run Multiple Tools (Multitask) action supports these shared fields:

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

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

Tool-specific parameters #

includeRawExif #

Used when metadata is included in the requested tools.

Type: boolean or string
Required: No
Default: false

Includes the raw EXIF object when the value is exactly true.

hashType #

Used with hash

Type: string
Required: No
Default: phash

Supported values:

• phash
• md5
• sha1
• sha256

similarityMode #

Used with similarity

Type: string
Required: No
Default: pairs

Supported values used in the public examples:

• pairs
• toFirst

similarityThreshold #

Used with similarity

Type: integer
Required: No
Default: 8
Range: 0 to 64

paletteSize #

Used with colors

Type: integer
Required: No
Default: 5
Range: 1 to 16

Controls palette sizing for colors analysis.

transparencySample #

Used with transparency

Type: integer
Required: No
Default: 64
Range: 16 to 128

qualitySample #

Used with quality

Type: integer
Required: No
Default: 256
Range: 64 to 512

efficiencyFormat #

Used with efficiency

Type: string
Required: No

Supported values:

• jpeg
• jpg
• png
• webp
• avif

efficiencyQuality #

Used with efficiency

Type: integer
Required: No
Default: 80
Range: 1 to 100

Full cURL Example #

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

This example uses the documented public multitask structure:

• action=multitask
• tools
• images
• flat tool-specific fields
• optional idempotency header

Success Response #

Successful /v1/tools requests return JSON analysis results.

The public response format is structured per uploaded image, with a tools object containing the outputs for each requested tool.

Use this public-safe example:

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

Response Fields #

results[] #

Array of analysis results, grouped by uploaded image.

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 /v1/tools endpoint uses the public error architecture for request validation, uploads, limits, availability, and tool execution. The documented error set relevant to this route includes:

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

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 → tool processing error (tool_processing_failed)

Usage Notes #

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

Use tools or tools[], not a nested tasks JSON structure.

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

All requested tools run against the uploaded images in the same request.

The /v1/tools endpoint returns JSON analysis results rather than generated file URLs.