Crop Image

Endpoint #

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

Action #

action=crop

Description #

Extracts a specific region from one or more images using the H2I engine (PixLab) image processing pipeline.

Cropping allows applications to remove unwanted areas and retain only the desired portion of an image. This is commonly used for thumbnails, profile images, product visuals, and automated content layouts. Crop 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 crop parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: crop

Specifies the crop operation.

images #

Type: file[]
Required: Yes

The source image file or files to crop.

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

cropX #

Type: integer
Required: No
Default: unset

Horizontal crop origin.

cropY #

Type: integer
Required: No
Default: unset

Vertical crop origin.

cropWidth #

Type: integer
Required: No
Default: unset

Crop rectangle width.

cropHeight #

Type: integer
Required: No
Default: unset

Crop rectangle height.

Crop Behavior #

The loaded external docs describe crop controls as a crop rectangle:

• cropX
• cropY
• cropWidth
• cropHeight

The public parameter table states these values are applied only if all are finite. Because you want strict source-based accuracy, this page should not claim different public field names or stronger validation behavior than what is documented.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-crop-001" \
  -F "action=crop" \
  -F "images=@./samples/a.jpg" \
  -F "cropX=0" \
  -F "cropY=0" \
  -F "cropWidth=800" \
  -F "cropHeight=600"

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

Response Fields #

• results[] — array of cropped 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 cropped 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.