Ssnap DocsBackgrounds, borders and watermarks
Backgrounds, borders and watermarks applied after the render.
Three post-capture manipulations are applied server-side, to image formats only. PDFs are returned untouched, and a request with none of these parameters skips post-processing entirely.
Colours are six hex digits, with an optional leading #: #1a1a1a and 1a1a1a are the
same value. Three-digit shorthand and named colours are rejected with 422.
Background
Fills transparent areas. Useful for PNG or WebP captures of pages with a transparent body.
--data-urlencode "background=#ffffff"Border
--data-urlencode "border_width=16" \
--data-urlencode "border_color=#111111"| Parameter | Range | Default |
|---|---|---|
border_width | 1–200 px | none |
border_color | hex colour | 000000 |
The border expands the image rather than cropping into it: a 1280×720 capture with
border_width=16 comes back 1312×752. border_color alone does nothing; the width is
what enables the border.
Watermark
--data-urlencode "watermark_text=© Example Ltd" \
--data-urlencode "watermark_size=28" \
--data-urlencode "watermark_color=#ffffff" \
--data-urlencode "watermark_x=40" \
--data-urlencode "watermark_y=40"| Parameter | Range | Default |
|---|---|---|
watermark_text | ≤255 chars | none |
watermark_size | 6–200 | 24 |
watermark_color | hex colour | ffffff |
watermark_x | 0–5000 | 20 |
watermark_y | 0–5000 | 20 |
watermark_x and watermark_y are pixel offsets from the top-left corner of the
image. To place text near the bottom of a known-height capture, set an explicit
height and compute the offset yourself, because coordinates are absolute rather than anchored.
Position watermarks with care on full_page captures: the image height depends on the
page's scroll height, so a fixed watermark_y may land anywhere. Watermark
viewport-sized or selector captures when placement matters.
Combining them
Order of application is background, then border, then watermark, so a watermark can sit on top of the border area.
curl -G https://ssnap.cc/api/v1/screenshot \
-H "Authorization: Bearer $SSNAP_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "format=png" \
--data-urlencode "width=1200" \
--data-urlencode "height=630" \
--data-urlencode "background=#0b0b0f" \
--data-urlencode "border_width=12" \
--data-urlencode "border_color=#2b2b35" \
--data-urlencode "watermark_text=example.com" \
--data-urlencode "watermark_size=22" \
--data-urlencode "watermark_color=#8f8fa3" \
--output og-image.pngStyling and the cache
All styling parameters are part of the cache key. Changing a watermark colour produces a fresh render and consumes a quota slot, so settle on your styling before warming a cache.