Compress Image

Endpoint #

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

Action #

action=compress

Description #

Reduces the file size of one or more images using the H2I engine (PixLab) image processing pipeline.

This operation is commonly used to optimize images for web delivery, reduce storage usage, and improve loading performance. Compression reduces file size while maintaining acceptable visual quality according to the selected encoder settings and route defaults. Compress 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 compression parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: compress

Specifies the compression operation.

images #

Type: file[]
Required: Yes

The source image file or files to compress.

Each uploaded image produces one result object in the response. Uploaded files must match the allowed image MIME types for the route.

targetSizeKB #

Type: integer
Required: No

Optional target file size hint in kilobytes. This is part of the documented public compression parameter set.

quality #

Type: integer
Required: No

Optional encoder quality control.

The loaded public docs describe quality as an integer-like parameter used in the encoder path, with clamping/search behavior handled internally by the route pipeline.

format #

Type: string
Required: No

Optional output format control for the compressed result. This parameter is part of the documented public compression action surface.

Compression Behavior #

The loaded public docs support these compression controls for action=compress:

• targetSizeKB
• quality
• format

Compression is applied independently to each uploaded image. The route uses the shared image-processing pipeline, and encoder-specific clamping/search behavior is handled internally. Because you want strict source-based accuracy, this page should not promise more specific quality semantics than the loaded public docs explicitly confirm.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-compress-001" \
  -F "action=compress" \
  -F "images=@./samples/a.jpg" \
  -F "targetSizeKB=200" \
  -F "quality=80"

This matches the documented external /v1/image compress 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,
      "quality": 80,
      "originalName": "a.jpg"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

• results[] — array of compressed image outputs
• url — output file URL
• format — output image format
• sizeBytes — file size
• width / height — final 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 output URLs in results[].

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 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 compressed 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 platform.