The problem
Photographers, schools, marketplaces and stock libraries all want a mark on the images they publish. Burning it in when the file is uploaded means keeping two copies, redoing every image when the logo changes, and no way to serve a clean version to the people who paid for it.
Drawing the mark when the image is served avoids all of that. The original stays untouched, the watermark is part of the URL, and changing it is a code change rather than a batch job.
Upload the logo once
An overlay is another image file in the same app, so upload your logo like any other file and keep its id. A PNG or WebP with a transparent background looks best. The image service only ever draws files your app already stores; it never fetches an image from a URL.
A logo in the corner
?transform=resize:1600x_;overlay:LOGO_ID~width:15pc~position:bottom-right~x:24~y:24~opacity:85width:15pc makes the logo 15% of the image's width whatever size the photo is, so it looks the same on a thumbnail and a full-size image. x and y move it in from the corner it is anchored to. Put the resize first so the logo is sized against the finished image.
A credit or a caption
?transform=text:%25C2%25A9%2520Jane%2520Doe~size:4pc~color:white~background:hex(00000080)~padding:8~position:bottom-left~x:16~y:16Text is URL-encoded inside the transform, and that is encoded again in the URL, which is why a space shows as %2520 above. The client libraries do both for you, so in code you write the text as it is. size:4pc is 4% of the image's height. background draws a box behind the text so it stays readable on any photo.
A repeated watermark
For proofs and previews, repeat the mark across the whole image so it cannot be cropped out. tile:true repeats the layer, gap spaces the copies, and rotate turns them for the familiar diagonal pattern.
?transform=resize:1200x_;text:PROOF~font:sans-bold~size:6pc~color:rgba(255,255,255,0.4)~rotate:-30~tile:true~gap:60
?transform=resize:1200x_;overlay:LOGO_ID~width:140~opacity:25~rotate:-30~tile:true~gap:60~transform:(grayscale)The second line also shows an overlay's own transforms: transform:(grayscale) makes the logo grey before it is drawn. Any resize, crop or colour transform can go there.
In code
import { Image } from "@cd2/fileboy-react"
<Image
id={photoId}
transforms={[
{ type: "resize", width: 1600 },
{ type: "overlay", file: LOGO_ID, width: { pc: 15 }, position: "bottom-right", x: 24, y: 24, opacity: 85 },
{ type: "text", text: "© Jane Doe", size: { pc: 4 }, color: "white", background: "#00000080", padding: 8, position: "bottom-left", x: 16, y: 16 },
{ type: "format", format: "auto" },
]}
/>const url = fileboy.buildImageUrl(photoId, {
transforms: [
{ type: "resize", width: 1200 },
{ type: "text", text: "PROOF", font: "sans-bold", size: { pc: 6 }, color: "rgba(255,255,255,0.4)", rotate: -30, tile: true, gap: 60 },
],
})url = client.build_image_url(photo_id, transforms=[
{"type": "resize", "width": 1600},
{"type": "overlay", "file": LOGO_ID, "width": {"pc": 15}, "position": "bottom-right", "x": 24, "y": 24},
])url = fileboy.build_image_url(photo_id, transforms: [
{ type: :resize, width: 1600 },
{ type: :overlay, file: LOGO_ID, width: { pc: 15 }, position: "bottom-right", x: 24, y: 24 }
])$url = $client->buildImageUrl($photoId, transforms: [
['type' => 'resize', 'width' => 1600],
['type' => 'overlay', 'file' => LOGO_ID, 'width' => ['pc' => 15], 'position' => 'bottom-right', 'x' => 24, 'y' => 24],
]);Keeping the clean original private
- A watermark in the URL does not hide the original: anyone who removes the transform gets the clean file. To sell or protect originals, set those files to Signed URLs only and sign the watermarked URL on your server. A signed URL covers its exact transform, so it cannot be edited to drop the watermark.
- If the logo itself is set to Signed URLs only, the image URL must be signed too, even for a public photo.
- Each different watermark is a different URL, transformed once and then cached.
- Up to 5 overlay and text layers can be drawn on one image. Text uses the bundled Go fonts, which cover Latin, Greek and Cyrillic.
- Watermarks on videos are not available yet.
Checked against the current libraries in November 2026. Found something that no longer works? Tell us.