Add Padding

Endpoint #

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

Action #

action=padding

Description #

Adds extra space around one or more images using the H2I engine (PixLab) image processing pipeline.

Padding is used to create borders or spacing around an image without modifying its original content. This is useful for layout alignment, fixed-dimension outputs, and preparing assets for visual templates. Padding 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 padding parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: padding

Specifies the padding operation.

images #

Type: file[]
Required: Yes

The source image file or files to process.

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

pad #

Type: integer
Required: No
Default: 0

Applies uniform padding on all sides. The public parameter table documents this as part of the padding field set.

padTop #

Type: integer
Required: No
Default: 0

Padding added to the top of the image.

padRight #

Type: integer
Required: No
Default: 0

Padding added to the right side of the image.

padBottom #

Type: integer
Required: No
Default: 0

Padding added to the bottom of the image.

padLeft #

Type: integer
Required: No
Default: 0

Padding added to the left side of the image.

padColor #

Type: string
Required: No
Default: #ffffff

Background color used for the padded area. The public parameter table documents padColor as the padding color field.

Padding Behavior #

The loaded public docs support these padding controls for action=padding:

• pad
• padTop
• padRight
• padBottom
• padLeft
• padColor

Padding increases the image canvas around the original content. The external API reference notes that non-finite padding values are ignored. Because you want strict source-based accuracy, this page should use the documented public field names above and should not add undocumented rejection behavior.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-padding-001" \
  -F "action=padding" \
  -F "images=@./samples/a.jpg" \
  -F "padTop=40" \
  -F "padRight=60" \
  -F "padBottom=40" \
  -F "padLeft=60" \
  -F "padColor=#ffffff"

This example uses the documented public padding parameter names for /v1/image.

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": 1320,
      "height": 880,
      "quality": 90,
      "originalName": "a.jpg"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

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