Add Watermark

Endpoint #

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

Action #

action=watermark

Description #

The Add Watermark action overlays watermark content onto one or more images using the H2I engine (PixLab) image processing pipeline.

Watermarks can be applied as:

• text overlays
• image overlays such as logos or branding assets

This operation is commonly used for:

• branding and ownership marking
• content protection
• visual labeling or annotation
• automated media processing workflows

Each uploaded image is processed independently and returned as a transformed output. Watermark is part of the public /v1/image processing surface.

Request Format #

Requests to /v1/image must use:

Content-Type: multipart/form-data

Images must be uploaded using the images field. The route also accepts one optional uploaded watermarkImage file for image-based watermarking.

Parameters #

action #

Type: string
Required: Yes
Value: watermark

Specifies the watermark operation.

images #

Type: file[]
Required: Yes

One or more source images.

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

watermarkText #

Type: string
Required: No

Text used as the watermark overlay.

watermarkImage #

Type: file
Required: No

Image file used as the watermark overlay. The /v1/image route accepts one optional uploaded watermarkImage.

Watermark Configuration #

watermarkOpacity #

Type: number
Required: No
Default: 0.35

Controls transparency of the watermark.

The public parameter tables document watermarkOpacity with route defaults and clamp it to 0..1.

watermarkPosition #

Type: string
Required: No
Default: center

Controls overlay placement.

Accepted values in the loaded public docs include:

• center
• top
• bottom
• left
• right
• corner positions

Invalid values fall back to center.

watermarkMargin #

Type: integer
Required: No
Default: 24

Controls spacing from image edges.

The public parameter tables clamp this value to 0..5000.

watermarkFontSize #

Type: integer
Required: No
Default: 32

Applies only to text watermarks.

The public parameter tables clamp this value to 6..400.

watermarkColor #

Type: string
Required: No
Default: #ffffff

Text color for the watermark.

The public docs describe this as a hex-like value, with white fallback behavior if parsing fails.

watermarkScale #

Type: number
Required: No
Default: 0.25

Controls the size of an image-based watermark.

The public parameter tables clamp this value to 0.01..1.

Processing Behavior #

Processing is applied independently to each uploaded image.

The loaded public docs support both text and image watermark inputs together with the watermark tuning fields above. Public documentation can safely say that the route accepts text watermarking, image watermarking, or both input types, but it should avoid promising a more specific composition order unless that behavior is standardized elsewhere in the source files.

Full cURL Example (All Supported Parameters) #

curl -sS -X POST "https://pixlab.davix.dev/v1/image" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: image-watermark-001" \
  -F "action=watermark" \
  -F "images=@./samples/a.jpg" \
  -F "watermarkText=PixLab" \
  -F "watermarkOpacity=0.35" \
  -F "watermarkPosition=center" \
  -F "watermarkMargin=24" \
  -F "watermarkFontSize=32" \
  -F "watermarkColor=#ffffff" \
  -F "watermarkScale=0.25"

This matches the documented external /v1/image watermark action surface and includes the supported public watermark tuning fields.

Success Response #

HTTP 200

Response body #

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

Response Fields #

• results[] — array of processed images
• url — signed output URL
• 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 signed output URLs 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 returned error path.

Usage Notes #

Authentication supports X-Api-Key and Authorization: Bearer <YOUR_API_KEY>. In production, API keys must be sent in headers.

Idempotency-Key is optional but 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.

Output is returned as URLs.

URLs are not guaranteed for permanent storage. Store results externally for long-term use. Public output URLs may be signed and time-limited.