SVG template watermarks
Text watermarks work well for a single block of text. When you need multiple text blocks, mixed text and images, or a precise layout, design the layout as an SVG template with placeholder variables, then fill in the actual content at request time.
Typical use cases: copyright watermarks with a username and date, product cards with a price and title, and certificates with a name and ID number.
How to use it
1. Create an SVG template
Put the variables {{TXT-1}}, {{TXT-2}}, and so on where the text should go in the SVG, then upload it to your bucket:
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="160">
<rect width="600" height="160" rx="16" fill="#000" fill-opacity="0.5"/>
<text x="32" y="72" font-family="NotoSansSC" font-size="44" font-weight="700" fill="#fff">{{TXT-1}}</text>
<text x="32" y="124" font-family="Inter" font-size="28" fill="#fff" fill-opacity="0.8">{{TXT-2}}</text>
</svg>2. Prepare the variable values
Write the text to fill in, in order, as a JSON array of strings, then Base64-encode it:
["Bitiful","2026-11-11"]
Encoded result:
WyJCaXRpZnVsIiwiMjAyNi0xMS0xMSJd
3. Send the request
Point mark to the template and pass the encoded content in txt:
Rules
| Item | Description |
|---|---|
| Variable format | {{TXT-N}}, where N is an integer from 1 to 10, without leading zeros |
| Mapping | {{TXT-1}} maps to the 1st array element, {{TXT-2}} to the 2nd, and so on |
| Reuse | The same variable can appear multiple times in a template; every occurrence is replaced |
| Array elements | Must all be strings; quote numbers too, e.g. "99" |
| Base64 | Both standard and URL-safe (-, _) encodings are accepted; trailing = padding can be omitted |
| Special characters | <, &, quotes, and similar characters in the content are escaped automatically and won't break the SVG structure |
Variable substitution doesn't take effect in any of the following cases:
- The
markpath doesn't end in.svg; - The template contains no
{{TXT-N}}variables; txtisn't valid Base64, or doesn't decode to an array of strings.
In these cases, txt is drawn on the image as a regular text watermark. Verify your encoding before going live.
If the array has fewer elements than the template has variables, any variable without a matching value is left as-is and displayed. Pass an empty string "" for any position you don't want to show.
Position and size
After substitution, the SVG is an ordinary image watermark, so its position, size, opacity, and other settings use the image watermark parameters:
mark-pos: position;mark-pct: size. The SVG is rendered as vectors at this ratio, so it stays sharp when scaled up;mark-alpha,mark-tile,mark-blend, and others work as well.
Template tips
- Fonts: For
font-family, use a font name listed in Watermark fonts; Chinese font names work too. - Emoji: Emoji in the text are rendered in color.
- Images: Images in the template must be embedded as
data:URIs; externally linked images aren't loaded. - Text width: SVG text doesn't wrap automatically, so leave enough room in the template for the longest content. Use
text-anchorto control alignment.
Encoding examples
JavaScript:
const txt = btoa(unescape(encodeURIComponent(JSON.stringify(["张三", "内部资料"]))))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
// WyLlvKDkuIkiLCLlhoXpg6jotYTmlpkiXQPython:
import base64, json
data = json.dumps(["张三", "内部资料"], ensure_ascii=False, separators=(",", ":"))
txt = base64.urlsafe_b64encode(data.encode()).decode().rstrip("=")
# WyLlvKDkuIkiLCLlhoXpg6jotYTmlpkiXQ