# SVG template watermarks

> Reserve variables in an SVG watermark template and fill in text dynamically at request time for multiple text blocks and complex layouts.

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

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

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

> **Note**
>
> 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](/en/coreix/features/watermark-image) 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](/en/coreix/features/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:

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

Python:

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