Add Frame

Endpoint #

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

Action #

action=frame

Description #

Adds a visual frame around one or more images using the H2I engine (PixLab) image processing pipeline.

Frames can be used to highlight content visually, create stylized outputs, or prepare images for presentation layouts such as social media assets, marketing materials, and application interfaces. Frame is part of the public /v1/image processing surface.

Request Format #

Send the request as multipart/form-data.

The source image is uploaded using the images field together with frame parameters. The /v1/image route is a multipart upload endpoint.

Parameters #

action #

Type: string
Required: Yes
Accepted value: frame

Specifies the frame operation.

images #

Type: file[]
Required: Yes

The source image file or files to process.

Each uploaded file produces one result in the response. Uploaded files are MIME-validated by the route.

border #

Type: integer
Required: No
Default: 0

Defines the thickness of the frame around the image.

The shared public parameter table documents border with a minimum of 0.

borderColor #

Type: string
Required: No
Default: #000

Specifies the color used for the frame.

borderRadius #

Type: integer
Required: No
Default: 0

Defines the radius of the frame corners.

The shared public parameter table documents borderRadius with a minimum of 0.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-frame-001" \
  -F "action=frame" \
  -F "images=@./samples/a.jpg" \
  -F "border=20" \
  -F "borderColor=#000000" \
  -F "borderRadius=12"

The loaded external cURL examples confirm action=frame with images, border, and borderColor, and the shared public parameter table confirms borderRadius as part of the same action surface.

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

The returned URL points to the generated image that includes the applied frame. For /v1/image, non-metadata actions return results[] items with output URL and file metadata.

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.

Usage Notes #

The public docs should use border, borderColor, and borderRadius for this action.

Multiple images can be processed in a single request by repeating the images field.

Output is returned as accessible URLs under /image/....

Authentication supports both X-Api-Key and Authorization: Bearer <key>.

Idempotency-Key is optional and recommended for safe retries. X-Idempotency-Key is also accepted, and a valid key is echoed back in the Idempotency-Key response header.