Image Multitask Processing

Endpoint #

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

Action #

action=multitask

Description #

The Image Multitask Processing action allows multiple image transformations to be applied in a single request using the H2I engine (PixLab) image processing pipeline.

Instead of sending multiple API requests, applications can include multiple transformation parameters in one request. The system processes each uploaded image using the provided parameters and returns the final result.

This is useful for workflows that require several modifications, such as resizing, format conversion, enhancement, background changes, watermarking, and compression.

Request Format #

Requests to /v1/image must use:

Content-Type: multipart/form-data

The source image must be uploaded using the images field.

Parameters #

action #

Type: string
Required: Yes
Value: multitask

Specifies that the request should apply multiple image transformations in a single operation.

images #

Type: file[]
Required: Yes

The source image file or files to process.

Supports one or multiple images. Each uploaded image produces one result in the response. Uploaded files are MIME-validated by the route.

Transformation Parameters #

All parameters below are optional and can be combined in a single request.

Resize and Format #

format #

Type: string
Required: No

Specifies the output format.

The shared public route docs confirm format handling in the multitask pipeline, including normalization of jpg to jpeg in format-handling paths. Because you want strict source-based accuracy, public docs should avoid overcommitting to broader format lists unless those lists are explicitly standardized in the source docs.

width / height #

Type: integer
Required: No

Defines resize controls for the output image. The shared route docs describe this as inside-fit resize behavior.

enlarge #

Type: boolean
Required: No
Default: false

Controls whether the image can be scaled up beyond its original size. The shared route docs describe this as controlling withoutEnlargement.

Crop #

cropX, cropY, cropWidth, cropHeight #

Type: integer
Required: No

Defines a crop region.

The shared public docs confirm that cropping is applied only when all four crop values parse as finite numbers.

Transform #

rotate #

Type: integer
Required: No

Rotates the image by the specified number of degrees when the value parses as finite.

flipH / flipV #

Type: boolean
Required: No

  • flipH → horizontal flip
  • flipV → vertical flip

Compression #

quality #

Type: integer
Required: No

Controls output quality through the encoder path. The shared public docs note that quality search/clamps are handled internally.

targetSizeKB #

Type: integer
Required: No

Attempts compression toward a target output size in kilobytes.

Enhancement #

blur #

Type: number
Required: No
Range: 0 → 500

Applies blur to the image.

sharpen #

Type: number
Required: No
Range: 0 → 10

Sharpens the image.

brightness / contrast / saturation #

Type: number
Required: No
Default: 1
Range: 0 → 2

Visual adjustment controls handled by the shared route pipeline.

grayscale / sepia #

Type: boolean
Required: No

Optional color-effect controls.

Padding and Borders #

pad, padTop, padRight, padBottom, padLeft #

Type: integer
Required: No
Default: 0

Adds spacing around the image. Non-finite values are ignored by the route.

padColor #

Type: string
Required: No
Default: #ffffff

Color used for padding.

border, borderRadius #

Type: integer
Required: No
Default: 0

  • border → thickness
  • borderRadius → rounded corners

Both are documented with minimum 0 behavior.

borderColor #

Type: string
Required: No
Default: #000

Color of the border.

Background #

backgroundColor #

Type: string
Required: No

Replaces the image background with a color.

backgroundBlur #

Type: number
Required: No
Range: 0 → 200

Applies blur behind the subject.

Watermark #

watermarkText #

Type: string
Required: No

Text watermark content.

watermarkImage #

Type: file
Required: No

Image used as watermark overlay. The /v1/image route accepts one optional uploaded watermarkImage.

watermarkOpacity #

Type: number
Required: No
Default: 0.35
Range: 0 → 1

Controls transparency.

watermarkPosition #

Type: string
Required: No
Default: center

Defines watermark placement. The route defaults invalid values to center.

watermarkMargin #

Type: integer
Required: No
Default: 24

Distance from edges.

watermarkFontSize #

Type: integer
Required: No
Default: 32

Text size for watermark.

watermarkColor #

Type: string
Required: No
Default: #ffffff

Text watermark color.

watermarkScale #

Type: number
Required: No
Default: 0.25
Range: 0.01 → 1

Controls the size of an image watermark.

Metadata and Orientation #

keepMetadata #

Type: boolean
Required: No
Default: false

Preserves metadata in the output image.

normalizeOrientation #

Type: boolean
Required: No
Default: false

Applies orientation correction based on EXIF data.

includeRawExif #

Type: boolean
Required: No
Default: false

Included as a shared field in the route docs, especially for metadata-related flows.

Color Space #

colorSpace #

Type: string
Required: No
Default: srgb

Supported values:

  • srgb
  • grayscale
  • cmyk

cmyk may fail and return invalid_parameter depending on build/runtime support.

PDF Output #

pdfMode #

Type: string
Required: No
Default: single

  • single → one image per PDF
  • multi → multiple images combined
pdfPageSize #

Type: string
Required: No
Default: auto

Supported values:

  • auto
  • a4
  • letter
pdfOrientation #

Type: string
Required: No
Default: portrait

  • portrait
  • landscape
pdfMargin #

Type: integer
Required: No
Default: 0

Defines page margins.

pdfEmbedFormat #

Type: string
Required: No
Default: png

Format used inside the PDF.

pdfJpegQuality #

Type: integer
Required: No
Default: 85
Range: 20 → 100

JPEG quality inside PDF.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: multitask-001" \
  -F "action=multitask" \
  -F "images=@./samples/photo.jpg" \
  -F "watermarkImage=@./samples/logo.png" \
  -F "format=jpeg" \
  -F "width=800" \
  -F "height=600" \
  -F "enlarge=false" \
  -F "cropX=0" \
  -F "cropY=0" \
  -F "cropWidth=800" \
  -F "cropHeight=600" \
  -F "rotate=90" \
  -F "flipH=true" \
  -F "flipV=false" \
  -F "targetSizeKB=200" \
  -F "quality=80" \
  -F "keepMetadata=false" \
  -F "normalizeOrientation=true" \
  -F "blur=10" \
  -F "sharpen=1" \
  -F "grayscale=false" \
  -F "sepia=false" \
  -F "brightness=1.1" \
  -F "contrast=1.1" \
  -F "saturation=1.1" \
  -F "pad=20" \
  -F "padTop=10" \
  -F "padRight=20" \
  -F "padBottom=10" \
  -F "padLeft=20" \
  -F "padColor=#ffffff" \
  -F "border=4" \
  -F "borderColor=#000000" \
  -F "borderRadius=12" \
  -F "backgroundColor=#ffffff" \
  -F "backgroundBlur=20" \
  -F "watermarkText=CONFIDENTIAL" \
  -F "watermarkFontSize=32" \
  -F "watermarkColor=#ffffff" \
  -F "watermarkOpacity=0.35" \
  -F "watermarkPosition=center" \
  -F "watermarkMargin=24" \
  -F "watermarkScale=0.25" \
  -F "colorSpace=srgb" \
  -F "pdfMode=single" \
  -F "pdfPageSize=auto" \
  -F "pdfOrientation=portrait" \
  -F "pdfMargin=0" \
  -F "pdfEmbedFormat=png" \
  -F "pdfJpegQuality=85" \
  -F "includeRawExif=true"

This full example uses the documented shared /v1/image multitask parameter surface and includes the optional watermarkImage upload as well.

Success Response #

Successful requests return HTTP 200.

Example #

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/image/...",
      "format": "jpeg",
      "sizeBytes": 84231,
      "width": 800,
      "height": 600,
      "originalName": "photo.jpg"
    }
  ],
  "request_id": "..."
}

Response Fields #

  • results[] → array of processed images
  • url → output file
  • format → image format
  • sizeBytes → file size
  • width / height → final dimensions
  • originalName → original filename
  • request_id → request identifier

For non-metadata /v1/image actions, the route returns result objects with signed output URLs and file metadata.

Errors #

The /v1/image endpoint may return:

  • 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 → server error

Usage Notes #

Idempotency-Key is optional and recommended. X-Idempotency-Key is also accepted, and valid values are echoed back in the Idempotency-Key response header.

Multiple transformations can be applied in a single request.

No task list is required — transformations are defined through parameters.

Output is returned as a URL in each results[] item.

Files should be stored externally for long-term use. Davix H2I is a processing service, not a permanent storage platform.

Was it helpful ?
Table of contents
Login
Login
Login
Login
Scroll to Top