Skip to content
Console

Text watermarks

All examples below use this source image: https://demo.bitiful.com/bridge.jpeg

Text watermarks apply only to static images. Animated images (GIF, animated WebP, APNG, and so on) are returned as-is, without a watermark.

Parameters

Text and font

ParameterDescriptionDefaultValues
txtWatermark text. If empty, no watermark is added. URL-encoding is recommended. %0A inserts a line break; emoji are supportedEmptyUp to 256 characters
txt-fontFont. Separate multiple fonts with commas; they are matched in order. Names are case-insensitive, and spaces and hyphens can be omittedNotoSansSCInter, NotoSansSC, NotoSansTC, SmileySans, and more
txt-langRegional glyph variant for Han characters. If omitted, it is detected automatically: text containing kana is treated as Japanese, text containing Hangul as Korean, and everything else as Simplified ChineseAutozh / zh-TW / zh-HK / ja / ko
txt-sizeFont size. Less than 1: calculated as a ratio of the image's shorter side; 1 or greater: set in pixelsAuto0 to 500
txt-weightFont weight, same as CSS font-weight400100 to 950
txt-line-heightLine height, as a multiplier, same as CSS line-height (px is not supported)1.10 to 100
txt-trackLetter spacing, in pixels0-50 to 200
txt-widthMaximum line width; text that exceeds it wraps automatically. CJK text can break between any two characters; Latin text breaks between wordsNo wrappingPixels, or a percentage (of the image width)
txt-alignAlignment for multi-line textleftleft / center / right

Color and effects

ParameterDescriptionDefaultValues
txt-colorText color. Separate multiple colors with commas to create a gradient, whose direction is set by txt-color-degFFF3-, 4-, 6-, or 8-digit hex (in 4- and 8-digit values, the last part is opacity), or a CSS color name
txt-color-degGradient angle; 90 means left to right900 to 360
txt-alphaOpacity: 0 is fully transparent, 1 is fully opaque. If omitted, the value of mark-alpha is used10 to 1
txt-shadShadow blur radius, in pixels; no shadow if omitted. Shadows are turned off automatically when txt-color is a gradientNo shadow0 to 50
txt-shad-posShadow offset, in pixels–0 to 100
txt-shad-colorShadow color; solid colors only666Same as txt-color
txt-lineOutline width, in pixels00 to 50
txt-line-colorOutline color000Hex (in 4- and 8-digit values, the first part is opacity)
txt-bgBackground box color. The box covers the text area plus txt-padNo background boxHex (in 4- and 8-digit values, the first part is opacity; e.g. 8000 is 50% black)
txt-radiusBackground box corner radius; requires txt-bg. 50% produces a pill shape0Pixels from 0 to 9999, or a percentage (of the box's shorter side)
txt-padPadding around the text, in pixels; with a background box, this is the box's inner padding00 to 9999
txt-blendBlend modenormalnormal / multiply / screen / overlay / darken / lighten / soft-light / hard-light / difference / add / subtract
mark-hdr-rateHDR brightness boost (shared with image watermarks). Applies only to HDR output with a gain map. 0 means no boost, 1 means maximum brightness0.50 to 1, or 0% to 100%

Position and size

ParameterDescriptionDefaultValues
txt-posWatermark position, in the form x,y. See "Position syntax" below0.95,0.93–
txt-pctMaximum size ratio. If the watermark is larger than the image width/height × this value, it is scaled down proportionally; a value greater than 1 lets the watermark extend beyond the image. Use x,y to constrain width and height separately1Greater than 0, up to 5
txt-rotRotation angle, clockwise. The background box, outline, and shadow rotate together with the text0-360 to 360
txt-tileTiling. Set to 1 to tile the watermark across the entire image, with alternate rows offsetOff1
txt-tile-gapTile spacing, in the form horizontal,vertical; percentages are relative to the watermark's own width and height50%Pixels or percentage
txt-tile-rotTile tilt angle0-90 to 90
txt-if-min-width
txt-if-min-height
Size threshold. No watermark is added if the image width or height is below this value, so thumbnails aren't covered by the watermarkNo limitPixels

Position syntax

The x and y values of txt-pos are independent, so you can mix different syntaxes. If you specify only one value, it applies to both directions. Positions are calculated against the processed image (after resizing and cropping).

Ratios (less than 1) support three anchoring modes:

SyntaxAnchorEffect
0.5Positioned proportionally within the range where the watermark stays fully inside the image: 0 is flush with the left/top edge, and values closer to 1 move it toward the right/bottom edgeThe watermark is always fully visible
*0.5The watermark's center is placed at this ratio of the imageNear an edge, up to half of the watermark can extend beyond the image
**0.5The watermark's left/top edge is placed at this ratio of the imageNear the right/bottom edge, the watermark can move entirely outside the image

Absolute values (1 or greater): the pixel offset of the watermark's top-left corner from the image's top-left corner.

We recommend setting txt-size and txt-pos to ratios less than 1. Source images vary in size and aspect ratio (especially after resizing and cropping with w and h), and ratios keep the watermark size and position consistent across images.

Examples

Demo 1: Add the text watermark Bitiful, with all other parameters at their defaults
Demo 2: Place the watermark at the bottom center, extending past the edge, with a font size of about 55% of the shorter side and 3% opacity
Demo 3: Shrink the watermark, move it to the center of the image, and apply a three-color left-to-right gradient

To make the watermark easier to see, this example also blurs the source image with blur=50.

URL: https://demo.bitiful.com/bridge.jpeg?txt=Bitiful&blur=50& txt-size=0.3 & txt-pos=0.5,0.5 & txt-color=03FF76,FFE05B,03FFFE

Text watermark: three-color gradient