Change Background

Endpoint #

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

Action #

action=background

Description #

Modifies the background of one or more images using the H2I engine (PixLab) image processing pipeline.

This operation allows applications to replace an image background with a solid color, apply blur behind the subject, or prepare images for marketing, product displays, profile images, and design-ready outputs. Background processing is handled per image within the image transformation pipeline.

Request Format #

Requests to /v1/image must use:

Content-Type: multipart/form-data

One or more image files must be uploaded using the images field. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Value: background

Specifies the background modification operation.

images #

Type: file[]
Required: Yes

The source image file or files to process.

Multiple files are supported. Each file produces one result in the response. Uploaded files must match the allowed image MIME types for the route.

backgroundColor #

Type: string
Required: No

Specifies the background color.

The public parameter table documents backgroundColor as one of the background action controls. Common customer-facing examples include hex values such as #ffffff and #000000.

backgroundBlur #

Type: number
Required: No

Applies blur behind the subject.

The public parameter table documents backgroundBlur as a numeric control in the background action surface, with route-level clamping in the shared pipeline.

Background Behavior #

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

• backgroundColor
• backgroundBlur

Processing is applied independently to each uploaded image. Because you want strict source-based accuracy, this page should use the documented public controls above and avoid adding behavior guarantees that are not explicitly described in the loaded source files.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-background-001" \
  -F "action=background" \
  -F "images=@./samples/a.png" \
  -F "backgroundColor=#ffffff" \
  -F "backgroundBlur=24"

This is aligned with the documented external /v1/image background action surface, which includes images, backgroundColor, and backgroundBlur.

Success Response #

Successful requests return HTTP 200.

Response body #

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/image/<generated-file>?exp=<...>&sig=<...>",
      "format": "png",
      "sizeBytes": 123456,
      "width": 1200,
      "height": 800,
      "quality": 90,
      "originalName": "a.png"
    }
  ],
  "request_id": "<REQUEST_ID>"
}

Response Fields #

• results[] — array of processed images
• url — signed URL to the output file
• format — output format
• sizeBytes — file size
• width / height — final dimensions
• originalName — original uploaded filename
• request_id — request identifier

For /v1/image, non-metadata actions return results[] with output URL and file metadata. Generated files are served from the public /image/* 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
• 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

The exact status depends on the specific error path returned by the route or middleware.

Usage Notes #

URLs may be time-limited and should not be used for permanent storage.

Store output externally for long-term use. Davix H2I is a processing service, not a permanent file storage service. Public output files are served from platform-managed output paths and cleaned up later.

Idempotency-Key is optional but recommended for safe retries. 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.

Output files are returned as URLs.