Convert Image Format

Endpoint #

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

Action #

action=format

Description #

Converts an input image into a different format using the H2I engine (PixLab) image processing pipeline.

Applications can upload one or more images and convert them into supported output formats such as PNG, JPEG, or WebP. This is commonly used to normalize assets, optimize images for delivery, or meet format requirements for downstream systems. Image format conversion is part of the public /v1/image processing surface.

Request Format #

Send the request as multipart/form-data.

The /v1/image endpoint accepts uploaded image files through the images form field together with action-specific form parameters.

Parameters #

action #

Type: string
Required: Yes
Accepted value: format

Specifies that the request performs image format conversion.

images #

Type: file[]
Required: Yes

The source image file or files to convert.

Multiple files can be uploaded by repeating the images field. The endpoint validates uploaded image MIME types against the allowed image set.

format #

Type: string
Required: No

Specifies the target output image format.

The public docs confirm that format=jpg is normalized to jpeg. Common supported values in the documented external examples and related conversion fields include:

• png
• jpeg
• jpg
• webp

The external cURL table marks this field as optional, using the source or encoder default when it is omitted.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-format-001" \
  -F "action=format" \
  -F "images=@./samples/a.png" \
  -F "format=jpeg"

This matches the documented external /v1/image format-conversion action model: multipart upload, action=format, uploaded images, and the requested output format.

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.png"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

• results[] — array of processed outputs
• url — link to the generated image
• format — output format
• sizeBytes — file size
• width / height — output dimensions
• request_id — request tracking identifier

The /v1/image route uses result-array responses for image-processing outputs. Generated files are served from the public /image/* output path.

Errors #

The /v1/image endpoint may return errors such as:

• 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. The route and upload documentation support these public error paths for /v1/image.

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 specific error condition returned by the route or middleware.

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 accepted, and valid values are echoed back in the Idempotency-Key response header.

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

Output is returned as accessible URLs in results[].

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