Extract Image Metadata

Endpoint #

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

Action #

action=metadata

Description #

The Extract Image Metadata action retrieves structured metadata from one or more uploaded images using the H2I engine (PixLab) image processing pipeline.

This action is designed for workflows that need to inspect image properties without performing local analysis. The uploaded file is analyzed by the backend processing infrastructure, and the response returns structured metadata for each uploaded image.

This capability is useful for asset inspection, validation workflows, media cataloging, and other automated pipelines that need to read image information programmatically.

Request Format #

Requests to /v1/image must use multipart/form-data because image files are uploaded with the request. The uploaded file is provided using the images field.

Parameters #

action #

Type: string
Required: Yes
Accepted value: metadata

Specifies that the request should extract metadata from the uploaded image.

images #

Type: file[]
Required: Yes

One or more source image files from which metadata will be extracted. The /v1/image route accepts image uploads through the images field.

normalizeOrientation #

Type: boolean
Required: No
Default: false

Controls whether orientation normalization is applied for metadata processing.

includeRawExif #

Type: boolean
Required: No
Default: false

When enabled, the response includes raw EXIF data when available.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-metadata-001" \
  -F "action=metadata" \
  -F "images=@./samples/a.jpg" \
  -F "normalizeOrientation=true" \
  -F "includeRawExif=true"

This example uploads an image and requests metadata extraction with both documented metadata-response controls enabled.

Success Response #

Successful requests return HTTP 200 and a metadata response.

Example #

{
  "results": [
    {
      "originalName": "a.jpg",
      "metadata": {
        "format": "jpeg",
        "width": 1200,
        "height": 800
      }
    }
  ],
  "request_id": "<REQUEST_ID>"
}

For the metadata action, the documented success shape is:

• results[]
• originalName
• metadata
• optional request_id

Unlike other /v1/image actions, this action returns structured metadata and does not return transformed output file URLs.

Response Fields #

• results[] → array of metadata results
• originalName → original uploaded filename
• metadata → structured metadata extracted from the image
• request_id → request identifier

Errors #

The /v1/image endpoint may return these errors during metadata extraction:

• 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
• 413 → upload limits exceeded
• 415 → unsupported media type
• 429 → rate limit or quota exceeded
• 503 → timeout or server busy
• 500 → processing error

Usage Notes #

X-Api-Key: <YOUR_API_KEY>

Idempotency-Key is optional and supported for /v1/* requests. X-Idempotency-Key is also accepted, and a valid key is echoed back in the Idempotency-Key response header.

Multiple images can be uploaded in one request through the images field.

This action returns structured metadata, not transformed output file URLs.

Authentication supports:

Authorization: Bearer <YOUR_API_KEY>