Resize Image

Endpoint #

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

Action #

action=resize

Description #

Resizes one or more images using the H2I engine (PixLab) image processing pipeline.

This operation accepts uploaded image files and generates resized versions based on the specified dimensions and resize controls. It is commonly used to prepare assets for web, mobile, reports, and automated workflows. Image resizing 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 resize parameters.

Parameters #

action #

Type: string
Required: Yes
Accepted value: resize

Specifies the resize operation.

images #

Type: file[]
Required: Yes

The source image file or files to resize.

Multiple files can be uploaded by repeating the images field. Each uploaded image produces a result object in the response. Uploaded files must match the allowed image MIME types for the route.

width #

Type: integer
Required: No

Target width control for resizing. The route parses integer-like input for width.

height #

Type: integer
Required: No

Target height control for resizing. The route parses integer-like input for height.

enlarge #

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

Controls whether the resize operation is allowed to enlarge the image. The public route documentation notes that this parameter controls withoutEnlargement behavior in the underlying image pipeline.

Resize Behavior #

The loaded public docs support this behavior:

• width and height are optional resize controls
• the resize path uses an inside-fit resize model
• enlarge=false prevents enlargement behavior

The loaded files do not explicitly document a public guarantee that supplying both width and height always forces exact output dimensions, and they do not document that omitting both must cause a validation error. Because you asked for strict source-based accuracy, this page should avoid those stronger claims unless you standardize and confirm them elsewhere in the source docs.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-resize-001" \
  -F "action=resize" \
  -F "images=@./samples/a.jpg" \
  -F "width=1024" \
  -F "height=768" \
  -F "enlarge=false"

This matches the documented external /v1/image resize example and includes the public resize controls documented for this action.

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": 1024,
      "height": 768,
      "quality": 90,
      "originalName": "a.jpg"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

• results[] — array of resized image outputs
• url — link to the generated output file
• format — output format
• sizeBytes — file size
• width / height — final output dimensions
• quality — output quality when relevant to the encoder path
• originalName — source filename
• request_id — request identifier

For non-metadata image actions, the public /v1/image route returns results[] with output URLs and per-file metadata.

Errors #

The /v1/image endpoint may return:

• invalid_parameter
• missing_field
• unsupported_media_type
• invalid_upload
• dimension_exceeded
• too_many_files
• total_upload_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 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

The exact status depends on the returned error code.

Usage Notes #

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

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

Multiple images can be resized in a single request by repeating the images field.

Output files are returned as URLs in results[].

Files that need long-term retention should be stored in your own systems after retrieval.