# Image watermarks

> Overlay an image watermark on your images: parameter reference and examples.

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

> **Warning**
>
> 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

| Parameter                               | Description                                                                                                                                                                                                                                          |   Default   | Values                                                                                                                                |
| :-------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------- |
| `mark`                                  | **Watermark image path**: the object's path in the bucket (e.g. `img/logo.png`). If empty, no watermark is added. URL-encoding is recommended                                                                                                        |    Empty    | An image in the same bucket                                                                                                           |
| `mark-pos`                              | **Watermark position**, in the form `x,y`. See "Position syntax" below                                                                                                                                                                               | `0.96,0.98` | –                                                                                                                                     |
| `mark-pct`                              | **Maximum 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 separately |     0.25    | Greater than 0, up to 5                                                                                                               |
| `mark-alpha`                            | **Opacity**: 0 is fully transparent, 1 is fully opaque                                                                                                                                                                                               |      1      | 0 to 1                                                                                                                                |
| `mark-blend`                            | **Blend mode**                                                                                                                                                                                                                                       |   `normal`  | `normal` / `multiply` / `screen` / `overlay` / `darken` / `lighten` / `soft-light` / `hard-light` / `difference` / `add` / `subtract` |
| `mark-tile`                             | **Tiling**. Set to `1` to tile the watermark across the entire image, with alternate rows offset                                                                                                                                                     |     Off     | `1`                                                                                                                                   |
| `mark-tile-gap`                         | **Tile spacing**, in the form `horizontal,vertical`; percentages are relative to the watermark's own width and height                                                                                                                                |    `50%`    | Pixels or percentage                                                                                                                  |
| `mark-tile-rot`                         | **Tile tilt angle**                                                                                                                                                                                                                                  |      0      | -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 watermark                                                                                                            |   No limit  | Pixels                                                                                                                                |
| `mark-hdr-rate`                         | **HDR brightness boost** (shared with text watermarks). Applies only to HDR output with a gain map. 0 means no boost, 1 means maximum brightness                                                                                                     |     0.5     | 0 to 1, or 0% to 100%                                                                                                                 |

> **Note**
>
> 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:

| Syntax  | Anchor                                                                                                                                                                                      | Effect                                                                        |
| :------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `0.5`   | Positioned 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 edge | The watermark is always fully visible                                         |
| `*0.5`  | The watermark's **center** is placed at this ratio of the image                                                                                                                             | Near an edge, up to half of the watermark can extend beyond the image         |
| `**0.5` | The watermark's **left/top edge** is placed at this ratio of the image                                                                                                                      | Near 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.

> **Tip**
>
> 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`**](https://demo.bitiful.com/bridge.jpeg?mark=static/img/bitiful-logo@3x.png\&mark-pos=0.5,0.95\&fmt=png)

![Image watermark: bottom center](https://demo.bitiful.com/bridge.jpeg?mark=static/img/bitiful-logo@3x.png\&mark-pos=0.5,0.95\&fmt=png)
