Skip to content
Console

Image watermarks

All examples below use this source image: https://demo.bitiful.com/bridge.jpeg

Image watermarks apply only to static images. Animated images (GIF, animated WebP, APNG, and so on) are returned as-is, without a watermark.

Parameters

Watermark image source

Supported formats: SVG / JPEG / PNG / WebP / AVIF / HEIC / BMP

  • The watermark image must be stored in the same bucket as the source image.
  • For a semi-transparent or irregularly shaped watermark, use a PNG, WebP, or AVIF with an alpha channel, or use an SVG.
  • SVG watermarks are rendered as vectors at the target size, so they stay sharp when scaled up (supported since July 2025).

Parameter overview

ParameterDescriptionDefaultValues
markWatermark image path: the object's path in the bucket (e.g. img/logo.png). If empty, no watermark is added. URL-encoding is recommendedEmptyAn image in the same bucket
mark-posWatermark position, in the form x,y. See "Position syntax" below0.96,0.98–
mark-pctMaximum size ratio. If the watermark is larger than the image width/height × this value, it is scaled down proportionally; a value greater than 1 lets the watermark extend beyond the image. Use x,y to constrain width and height separately0.25Greater than 0, up to 5
mark-alphaOpacity: 0 is fully transparent, 1 is fully opaque10 to 1
mark-blendBlend modenormalnormal / multiply / screen / overlay / darken / lighten / soft-light / hard-light / difference / add / subtract
mark-tileTiling. Set to 1 to tile the watermark across the entire image, with alternate rows offsetOff1
mark-tile-gapTile spacing, in the form horizontal,vertical; percentages are relative to the watermark's own width and height50%Pixels or percentage
mark-tile-rotTile tilt angle0-90 to 90
mark-if-min-width
mark-if-min-height
Size threshold. No watermark is added if the image width or height is below this value, so thumbnails aren't covered by the watermarkNo limitPixels
mark-hdr-rateHDR brightness boost (shared with text watermarks). Applies only to HDR output with a gain map. 0 means no boost, 1 means maximum brightness0.50 to 1, or 0% to 100%

For raster watermarks, mark-pct is an upper bound: the watermark is only scaled down, never up. For SVG watermarks, it is the target size: the watermark is rendered at that ratio.

Position syntax

The x and y values of mark-pos are independent, so you can mix different syntaxes. If you specify only one value, it applies to both directions. Positions are calculated against the processed image (after resizing and cropping).

Ratios (less than 1) support three anchoring modes:

SyntaxAnchorEffect
0.5Positioned proportionally within the range where the watermark stays fully inside the image: 0 is flush with the left/top edge, and values closer to 1 move it toward the right/bottom edgeThe watermark is always fully visible
*0.5The watermark's center is placed at this ratio of the imageNear an edge, up to half of the watermark can extend beyond the image
**0.5The watermark's left/top edge is placed at this ratio of the imageNear the right/bottom edge, the watermark can move entirely outside the image

Absolute values (1 or greater): the pixel offset of the watermark's top-left corner from the image's top-left corner.

We recommend setting mark-pos to a ratio less than 1. Source images vary in size and aspect ratio (especially after resizing and cropping with w and h), and ratios keep the watermark position consistent across images.

Example

Place the logo stored in the bucket at the bottom center of the image:

URL: https://demo.bitiful.com/bridge.jpeg? mark=static/img/bitiful-logo@3x.png & mark-pos=0.5,0.95

Image watermark: bottom center