Transform Image

Endpoint #

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

Action #

action=transform

Description #

Applies geometric transformations to one or more images using the H2I engine (PixLab) image processing pipeline.

This action allows applications to modify images through operations such as rotation and flipping. It is commonly used to normalize orientation, align assets, or prepare images for downstream processing. Transform is part of the public /v1/image processing surface.

Request Format #

Send the request as multipart/form-data.

Image files must be uploaded through the images form field together with transformation parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: transform

Specifies the transformation operation.

images #

Type: file[]
Required: Yes

The source image file or files to transform.

Each uploaded image produces one result object in the response. Uploaded files must be valid image uploads accepted by the route.

rotate #

Type: integer
Required: No

Rotation angle.

The public parameter table documents rotate as an integer-like transform control that is applied only when it parses as a finite value.

flipH #

Type: boolean or boolean-like string
Required: No
Default: false

Applies a horizontal flip when enabled.

flipV #

Type: boolean or boolean-like string
Required: No
Default: false

Applies a vertical flip when enabled.

Transformation Behavior #

The loaded public docs support these transformation controls for action=transform:

• rotate
• flipH
• flipV

Transformations are applied per uploaded image. The public parameter documentation confirms that rotate is used only when it parses as a finite value, and that horizontal and vertical flip controls are exposed as separate boolean-like fields. Because you want strict source-based accuracy, this page should not introduce undocumented field names or undocumented operation-order guarantees.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-transform-001" \
  -F "action=transform" \
  -F "images=@./samples/a.jpg" \
  -F "rotate=90" \
  -F "flipH=true"

This matches the documented external /v1/image transform example.

Success Response #

Successful requests return HTTP 200.

Response body #

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/image/<generated-file>?exp=<...>&sig=<...>",
      "format": "jpeg",
      "sizeBytes": 123456,
      "width": 1200,
      "height": 800,
      "originalName": "a.jpg"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

• results[] — array of transformed image outputs
• url — output file URL
• format — image format
• sizeBytes — file size
• width / height — final output dimensions
• originalName — source filename
• request_id — request identifier

For non-metadata image actions, the public /v1/image route returns output URLs in results[]. Generated files are served from the public /image/* output path.

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
• monthly_quota_exceeded
• server_busy
• timeout
• image_processing_failed

Authentication and idempotency errors can also occur.

HTTP Status Codes #

• 400 → invalid request or invalid parameter
• 413 → upload or file-count limit exceeded
• 415 → unsupported media type
• 429 → rate limit or quota exceeded
• 500 / 503 → processing, timeout, or service-availability errors depending on failure path

Usage Notes #

Authentication supports both X-Api-Key and Authorization: Bearer <key> on public /v1/* routes.

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 images can be transformed in a single request by repeating the images field.

Output is returned as URLs in results[].

Files that need long-term retention should be stored in your own systems after retrieval. Davix H2I is a processing service, not a long-term storage or hosting platform.