Enhance Image

Endpoint #

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

Action #

action=enhance

Description #

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

Image enhancement is used to adjust visual characteristics such as sharpness, contrast, brightness, saturation, blur, grayscale conversion, or sepia styling. This operation is used to prepare images for presentation, distribution, or downstream workflows. Enhance 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 enhancement parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: enhance

Specifies the enhancement operation.

images #

Type: file[]
Required: Yes

The source image file or files to enhance.

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

blur #

Type: number
Required: No

Optional blur control.

The public parameter table documents blur as a numeric enhancement control with clamping in the shared pipeline.

sharpen #

Type: number
Required: No

Optional sharpen control.

The public parameter table documents sharpen as a numeric enhancement control with clamping in the shared pipeline.

brightness #

Type: number
Required: No
Default: 1

Optional brightness adjustment. The public parameter table documents brightness as a number-like field clamped in the shared pipeline.

contrast #

Type: number
Required: No
Default: 1

Optional contrast adjustment. The public parameter table documents contrast as a number-like field clamped in the shared pipeline.

saturation #

Type: number
Required: No
Default: 1

Optional saturation adjustment. The public parameter table documents saturation as a number-like field clamped in the shared pipeline.

grayscale #

Type: boolean or boolean-like string
Required: No

Optional grayscale conversion control.

sepia #

Type: boolean or boolean-like string
Required: No

Optional sepia styling control.

Enhancement Behavior #

The loaded public docs support these enhancement controls for action=enhance:

• blur
• sharpen
• brightness
• contrast
• saturation
• grayscale
• sepia

Enhancement is applied independently to each uploaded image. The exact pipeline behavior is handled by the shared image-processing layer. Because you want strict source-based accuracy, this page should use the documented public controls above and should not introduce an undocumented strength field.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-enhance-001" \
  -F "action=enhance" \
  -F "images=@./samples/a.jpg" \
  -F "sharpen=1" \
  -F "contrast=1.1"

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

Response Fields #

• results[] — array of enhanced image outputs
• url — output file URL
• format — 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 enhanced 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.