Skip to content

Text Overlay Parameters

The text overlay feature allows you to add text on top of images with fine-grained control over typography, positioning, and layout. Provide parameters as URL query strings (URL-encode the values) or use base64 helpers for complex content.

Content and Fonts

txt / txt64

Main text string. Supply URL-encoded text via txt, or use URL-safe base64 through txt64 when you need special characters or multi-line content. If no text value is provided, no overlay is rendered.

Type: string

txt_font / txt_font64

Font family used for rendering. Defaults to Liberation Sans when omitted. Use txt_font64 for base64-encoded font names.

Type: string

txt_size

Font size in pixels.

Type: integer
Default: 24
Typical range: 8-300

txt_color

Text colour value. Accepts named colours, hex (#RRGGBB), RGB/RGBA, and other colour string formats.

Type: string
Default: #ffffff

Positioning

txt_align

Comma-separated alignment keywords that anchor the text block relative to the base image. Supported values: top, middle, bottom, left, center/centre, right. Without txt_align, the text defaults to the top-left corner.

Type: string

txt_x, txt_y

Absolute pixel coordinates for manual placement. When provided, these override txt_align.

Type: integer

txt_pad

Padding applied around the text when using alignment anchors.

Type: integer
Default: 0
Range: >= 0

Layout and Fitting

txt_width

Maximum allowed width in pixels before clipping or scaling is considered.

Type: integer (> 0)

txt_fit

Automatic scaling behaviour. Currently supports max, which downscales oversized text to fit within txt_width while preserving aspect ratio.

Type: string (max)

txt_clip

Clipping behaviour when text exceeds txt_width. Combine values such as start, middle, end, and optional ellipsis (e.g. middle,ellipsis).

Type: string

Styling Enhancements

txt_line, txt_line_color

Outline thickness in pixels and optional outline colour. When txt_line is 0 or omitted, no outline is drawn. Outline colour defaults to the main text colour.

Type: integer (>= 0) and string

txt_lead

Additional line spacing in pixels, applied relative to the base font size. Useful for multi-line copy.

Type: integer (>= 0)

txt_track

Letter tracking in thousandths of an em. Adjusts spacing between characters for display typography.

Type: integer (>= 0)

txt_shad

Drop-shadow offset and strength in pixels. Higher values create a softer, more pronounced shadow. Set to 0 to disable.

Type: integer (>= 0, practical range 0-20)

Usage

Basic Text Overlay

image.jpg?txt=Hello%20World&txt_size=48&txt_color=white
Adds white 48px text in the top-left corner.

Anchored Caption with Padding

image.jpg?txt=Copyright%202024&txt_align=bottom,right&txt_pad=24&txt_size=18&txt_color=rgba(255,255,255,0.7)
Anchors the caption bottom-right with 24px padding.

Auto-Fitting Headline

image.jpg?txt=Limited%20Time%20Offer&txt_width=640&txt_fit=max&txt_align=top,center&txt_size=96
Scales the headline down to fit within 640px when necessary.

Outlined Text with Shadow

image.jpg?txt=SALE&txt_size=72&txt_color=#ff0000&txt_line=4&txt_line_color=white&txt_shad=6&txt_align=center,middle
Adds a bold centre overlay with a white outline and soft drop shadow.

Base64-Encoded Multi-line Copy

image.jpg?txt64=U2Vhc29uIEVuZHM=&txt_font64=Sm9zZWZpbg==&txt_align=top,left&txt_lead=8
Decodes the supplied base64 strings before rendering, keeping URLs clean.

Tips

  • URL-encode spaces (%20) or switch to txt64 for complex strings and emojis.
  • Combine txt_align with txt_pad for consistent gutters across responsive layouts.
  • Layer watermarks after text overlays when you need branding to sit above captions.
  • Use contrasting outline (txt_line_color) or drop shadow (txt_shad) to keep text legible over busy backgrounds.

Troubleshooting

  • No text rendered: ensure txt/txt64 is provided and not empty.
  • Unexpected position: remove txt_x/txt_y when relying on alignment, or adjust padding values.
  • Clipping issues: set txt_width and combine with txt_fit=max, or alter txt_clip to middle,ellipsis.
  • Font fallback: confirm the requested font is available; if not, provide an exact match via txt_font64.
  • Shadow too strong: lower txt_shad; values of 4-6 give a subtle lift.