Watermark Image API

Introduction

Watermark Image API lets you add text or logo watermarks to any number of images programmatically — no Photoshop, no manual work, no third-party accounts. Provide a list of image URLs or Apify Key-Value Store keys, configure your watermark once, and get back professionally branded output images in PNG, JPEG, or WebP format.

Built on Sharp.js (libvips), all processing happens locally on Apify infrastructure — your images are never sent to an external service. Primary use cases include portfolio protection for photographers, product image branding for e-commerce sellers, stock photo preview generation, real estate listing watermarks, and batch campaign asset preparation for marketing teams.

Key differentiators:

• Batch processing — up to 1,000 images per run
• 9-position placement — top/center/bottom × left/center/right corners
• Tiled/repeated watermarks — cover the entire image with a grid pattern
• Zero-config — just provide image URLs and optional text, everything else has sensible defaults
• No external dependencies — processes locally, no image data leaves Apify

Why Use This Actor

There is no dedicated image watermarking actor on the Apify Store. Until now, users had to download images, process them in desktop software (Photoshop, GIMP), or use online tools (Watermarkly, iLoveIMG) with severe batch limits, then re-upload — a workflow that does not scale.

Cost comparison:

Service	Cost per 1,000 images
Watermark Image API (this actor)	$2.60
Cloudinary transformations	~$20+
iLoveIMG API	~$10
Watermarkly	~$5 (manual)

No external API key required — run directly from the Apify platform with full ecosystem support: scheduling, webhooks, API integration, and storage.

How to Use

Zero-config example — provide image URLs and use default text watermark:

{
  "images": [
    { "url": "https://example.com/photo.jpg" },
    { "url": "https://example.com/product.png" }
  ]
}

Text watermark with custom position and opacity:

{
  "images": [{ "url": "https://example.com/photo.jpg" }],
  "watermarkType": "text",
  "text": "© MyBrand 2026",
  "fontSize": 36,
  "fontColor": "#FFFFFF",
  "position": "bottom-center",
  "opacity": 0.7,
  "rotation": -45
}

Logo watermark with tiling for full-image protection:

{
  "images": [{ "url": "https://example.com/product.jpg" }],
  "watermarkType": "image",
  "watermarkImageUrl": "https://example.com/logo.png",
  "watermarkScale": 0.15,
  "tiled": true,
  "tileSpacing": 80,
  "opacity": 0.3
}

Downloading results from KV Store:

After the run, each dataset item contains an outputUrl field — a direct download link to the watermarked image in the Apify Key-Value Store. You can also browse the KV Store tab in the Apify Console.

Input Configuration

Parameter	Type	Default	Description
images	array	—	Required. Array of { "url": "..." } or { "kvStoreKey": "..." } objects. Max 1,000.
watermarkType	string	"text"	"text" or "image"
text	string	"Sample"	Text to overlay (max 200 chars)
fontSize	integer	48	Font size in pixels (8–500)
fontColor	string	"#FFFFFF"	Hex color or CSS name
fontFamily	string	"sans-serif"	sans-serif, serif, or monospace
customFontUrl	string	null	URL to TTF/OTF font file
fontWeight	string	"bold"	"normal" or "bold"
textStroke	boolean	true	Outline around text for readability
watermarkImageUrl	string	null	Logo URL for image watermarks
watermarkScale	number	0.2	Logo size relative to image width (0.01–1.0)
position	string	"bottom-right"	One of 9 positions
opacity	number	0.5	0.01 (nearly invisible) to 1.0 (solid)
rotation	integer	0	Degrees; -45 = classic diagonal
padding	integer	20	Edge padding in pixels
tiled	boolean	false	Grid pattern across entire image
tileSpacing	integer	100	Pixels between tiles
outputFormat	string	"png"	png, jpeg, or webp
outputQuality	integer	90	Quality for JPEG/WebP (1–100)
outputPrefix	string	"watermarked_"	Prefix for KV Store output keys
maxOutputWidth	integer	null	Cap output width (preserves aspect ratio)
maxConcurrency	integer	5	Parallel processing (1–20)
imageTimeout	integer	30000	Per-image download timeout in ms

Common configurations:

Quick text watermark — just set images and optionally text. All other defaults produce a clean bottom-right white bold watermark.

Logo branding — set watermarkType: "image", watermarkImageUrl, watermarkScale: 0.2, position: "bottom-right", opacity: 0.8.

Full protection — set tiled: true, rotation: -45, opacity: 0.25, tileSpacing: 120 for a semi-transparent diagonal repeat pattern.

Output Format

Dataset item (one per image):

{
  "sourceUrl": "https://example.com/photo.jpg",
  "sourceKvKey": null,
  "outputKvKey": "watermarked_image_1.png",
  "outputUrl": "https://api.apify.com/v2/key-value-stores/abc123/records/watermarked_image_1.png",
  "originalWidth": 1920,
  "originalHeight": 1080,
  "outputWidth": 1920,
  "outputHeight": 1080,
  "originalSizeBytes": 524288,
  "outputSizeBytes": 612345,
  "outputFormat": "png",
  "watermarkType": "text",
  "watermarkPosition": "bottom-right",
  "watermarkTiled": false,
  "processingTimeMs": 320,
  "processedAt": "2026-03-11T12:00:00.000Z",
  "errors": []
}

Run summary (KV Store OUTPUT key):

{
  "totalProcessed": 50,
  "totalSuccess": 49,
  "totalFailed": 1,
  "totalInputSizeBytes": 26214400,
  "totalOutputSizeBytes": 30638080,
  "averageProcessingTimeMs": 285,
  "outputFormat": "png",
  "watermarkType": "text",
  "durationMs": 14200
}

Images are stored in the default KV Store with the configured outputPrefix. The outputUrl in each dataset record is a direct, stable download link.

Tips and Advanced Usage

Text vs image watermarks: Text watermarks are simpler to configure and render clearly at any resolution. Image/logo watermarks preserve brand identity but require a high-quality PNG with transparency for best results — JPEG logos will have a rectangular background.

Optimal opacity: 0.4–0.6 is the sweet spot for visible-but-non-intrusive watermarks. For preview/protection use cases where you want to deter unauthorized use, 0.7–0.9 works better.

Tiled watermarks for maximum protection: Use tiled: true with rotation: -45 and opacity: 0.2–0.3. This makes the watermark nearly impossible to crop or clone-stamp out while keeping the image recognizable.

Custom fonts: Point customFontUrl at any publicly accessible TTF or OTF file. The font is downloaded once and reused for the entire batch. If the URL is invalid or the file is not a font, processing continues with the selected fallback fontFamily.

Large batch processing: For 1,000-image runs, set memoryMbytes: 4096 in the run options and maxConcurrency: 10. This processes roughly 1,000 standard images in under 10 minutes.

Integration with scrapers: Combine with Web Scraper or any URL-extraction actor — pipe image URLs directly into images for a fully automated watermarking pipeline.

Related Junipr actors: Image to PDF | Multi-Resolution Screenshot | PDF OCR Tool

Pricing

Pay-Per-Event pricing: $2.60 per 1,000 images watermarked ($0.0026 per image).

Pricing includes all platform compute costs — no hidden fees.

You are only charged for successfully watermarked images. Images that fail to download or cannot be processed are never charged.

Scenario	Images	Estimated Cost
Single image	1	$0.0026
Product catalog	50	$0.13
Photography portfolio	500	$1.30
E-commerce store	5,000	$13.00
Stock photo library	50,000	$130.00

Compared to Cloudinary ($20+/1K), iLoveIMG API ($10/1K), or Watermarkly ($5/1K manual), this actor is 3–13× cheaper with no account setup and full API access.

FAQ

What image formats are supported?

All formats Sharp.js supports: JPEG, PNG, WebP, AVIF, TIFF, GIF, HEIC, and BMP. For animated GIF/WebP input, only the first frame is processed. Output is always in the uniform format set by outputFormat (png, jpeg, or webp).

Can I use my company logo as a watermark?

Yes. Set watermarkType: "image" and provide your logo URL in watermarkImageUrl. PNG with a transparent background gives the cleanest result — JPEG logos will include a rectangular background box. Control size with watermarkScale (0.2 = 20% of image width).

How do tiled watermarks work?

When tiled: true, the watermark (text or image) is repeated across the entire image in a grid pattern. The tileSpacing parameter controls the gap between instances. Combined with rotation: -45, this creates the classic diagonal repeating pattern used by stock photo sites.

What happens if an image URL is broken?

The image is skipped with an IMAGE_NOT_FOUND error recorded in the dataset item's errors field. Processing continues with remaining images. You are not charged for failed images. The run summary counts both successes and failures.

Can I watermark images stored in Apify KV Store?

Yes. Use { "kvStoreKey": "my-image-key" } instead of { "url": "..." } in the images array. The actor reads from the default KV Store of the current run. Make sure the key exists before starting.

Does watermarking reduce image quality?

For PNG output: no quality loss — PNG is lossless. For JPEG/WebP output: quality is controlled by outputQuality (default 90), which produces visually identical output at a smaller file size. Source images with transparency converted to JPEG are composited onto a white background.

Can I use custom fonts?

Yes. Set customFontUrl to a publicly accessible TTF or OTF file URL. The font downloads once and is reused across the entire batch. If the URL is unreachable or the file is invalid, the actor falls back to the fontFamily setting (sans-serif/serif/monospace) and logs a warning.

What's the maximum batch size?

1,000 images per run. For larger libraries, split into multiple runs of 1,000 each. Set maxConcurrency: 10 and allocate 4096 MB of memory for high-throughput processing. At concurrency 10, a batch of 1,000 standard images typically completes in under 10 minutes.