Watermark
PreviewProxy can overlay a watermark on top of a source image. Two watermark types are supported: image (wm) and text (wmt). If both are provided, wm takes priority.
Image watermark
The wm parameter accepts a URL pointing to the watermark image. The watermark is composited over the source image according to the placement parameters.
Path-style
/wm:<watermark-url>/<source-url>
/wm:https://example.com/logo.png/https://example.com/photo.jpg
Query-style
/proxy?url=https://example.com/photo.jpg&wm=https%3A%2F%2Fexample.com%2Flogo.png
Use a PNG watermark with transparency for best results. The alpha channel is preserved during compositing.
Supported watermark URL sources
| Source | Example |
|---|---|
| HTTP | http://example.com/watermark.png |
| HTTPS | https://example.com/watermark.png |
| S3 | s3:/bucket/path/watermark.png |
| Local | local:/path/to/watermark.png |
| Alias | mycdn:/path/to/watermark.png |
Scale
wm_scale sets the watermark width as a fraction of the source image width. The height is scaled proportionally. Omit or set to 0 to use the watermark's natural size.
| Parameter | Type | Default | Description |
|---|---|---|---|
wm_scale | float | 0 | Watermark width as a fraction of source width (0-1) |
/wm:https://example.com/logo.png,wm_scale:0.2/https://example.com/photo.jpg
Text watermark
The wmt parameter renders a text string as a watermark overlay.
Path-style
/wmt:<text>/<source-url>
/wmt:Copyright 2025/https://example.com/photo.jpg
Query-style
/proxy?url=https://example.com/photo.jpg&wmt=Copyright+2025
Text styling parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
wmt_color | string | 000000 | Text color as a 6-digit hex code (no #) |
wmt_size | int | 24 | Font size in pixels |
wmt_font | string | sans | Font name (see Fonts below) |
/wmt:Copyright 2025,wmt_color:ffffff,wmt_size:32,wmt_font:sans/https://example.com/photo.jpg
Fonts
The value sans (or an empty string) uses the bundled default font. Any other value is looked up from the system font directories:
/usr/share/fonts/truetype/<name>.ttf/usr/share/fonts/<name>.ttf/usr/local/share/fonts/<name>.ttf/usr/share/fonts/truetype/<name>/<name>.ttf
If the named font is not found, PreviewProxy falls back to the bundled default font. Path traversal characters (/, \, ..) are rejected.
Shared placement parameters
These parameters apply to both image and text watermarks.
| Parameter | Type | Default | Description |
|---|---|---|---|
wm_pos | string | noea | Position anchor (see table below) |
wm_x | int | 0 | Horizontal offset in pixels (can be negative) |
wm_y | int | 0 | Vertical offset in pixels (can be negative) |
wm_opacity | float | 1.0 | Opacity from 0.0 (transparent) to 1.0 (full) |
Position values (wm_pos)
nowetop-lefttlnorth_westnotoptnorthnoeatop-righttrnorth_east* default
weleftlwestcecentercearightreastsowebottom-leftblsouth_westsobottombsouthsoeabottom-rightbrsouth_east* default when wm_pos is not specified.
| Value | Description | |||
|---|---|---|---|---|
| Short | Alias | Abbr | Named | |
nowe | top-left | tl | north_west | Top-left corner |
no | top | t | north | Top edge, centered |
noea | top-right | tr | north_east | Top-right corner (default) |
we | left | l | west | Left edge, centered |
ce | center | c | Center | |
ea | right | r | east | Right edge, centered |
sowe | bottom-left | bl | south_west | Bottom-left corner |
so | bottom | b | south | Bottom edge, centered |
soea | bottom-right | br | south_east | Bottom-right corner |
re | repeat | rep | Tile across the entire image | |
re / repeat / rep - tile across entire image (see Tiling below).
Tiling (re)
When wm_pos is re, the watermark is tiled across the entire image. wm_x and wm_y control the spacing between tiles (in pixels) instead of acting as a positional offset.
/wm:https://example.com/logo.png,wm_pos:re,wm_x:20,wm_y:20/https://example.com/photo.jpg
Combining with other transforms
Watermark parameters can be combined with resize, format conversion, and other transforms in the same request.
/w=1200,webp,wm:https://example.com/logo.png,wm_pos:sowe,wm_opacity:0.6/https://example.com/photo.jpg
Query-style with text watermark:
/proxy?url=https://example.com/photo.jpg&w=800&wmt=Copyright+2025&wmt_color=ffffff&wmt_size=28&wm_pos=soea&wm_opacity=0.8