Skip to content
Console

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:

https://demo.bitiful.com/girl.jpeg?mark=templates/card.svg&txt=WyJCaXRpZnVsIiwiMjAyNi0xMS0xMSJd&mark-pos=0.05,0.95&mark-pct=0.5

Rules

ItemDescription
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
ReuseThe same variable can appear multiple times in a template; every occurrence is replaced
Array elementsMust all be strings; quote numbers too, e.g. "99"
Base64Both 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 mark path doesn't end in .svg;
  • The template contains no {{TXT-N}} variables;
  • txt isn'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-anchor to control alignment.

Encoding examples

JavaScript:

 const txt = btoa(unescape(encodeURIComponent(JSON.stringify(["张三", "内部资料"]))))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
// WyLlvKDkuIkiLCLlhoXpg6jotYTmlpkiXQ

Python:

import base64, json
 data = json.dumps(["张三", "内部资料"], ensure_ascii=False, separators=(",", ":"))
txt = base64.urlsafe_b64encode(data.encode()).decode().rstrip("=")
# WyLlvKDkuIkiLCLlhoXpg6jotYTmlpkiXQ