Watermark

Image Watermark

Overlay a logo or image on every page of a PDF — placed in a corner, centred, or tiled into a repeating branded grid. PNG transparency is honoured.

Free to try — no key required 10 credits / callSynchronous

Overview

Send the PDF and the watermark image as two file parts. The image is applied to every page, sized relative to the page rather than in raw pixels. On the free-try path.

POSThttps://api.bytefuse.in/api/v1/watermark/image

Request

Content type multipart/form-data — two file parts plus form fields:

filefilerequired

The PDF to watermark.

watermarkfilerequired

The watermark image. PNG or JPEG only (else 422). Auto-downscaled to a max side of 1000px; PNG alpha is composited.

positionstringoptional

Same position set as the text watermark (center, top-left, bottom-right, …). Ignored when tile is true.Default: center

opacityfloatoptional

0.0–1.0. Baked into the image’s alpha channel.Default: 0.5

scalefloatoptional

0.1–2.0, relative to the page. Non-tiled 1.0 ≈ 30% of page width; tiled base ≈ 15% × scale. Not raw pixels.Default: 1.0

tilebooleanoptional

Repeat the logo across the whole page in a staggered grid. position is ignored.Default: false

Response

200 OK, application/json — same shape as the text watermark:

200 OK

{
  "success": true,
  "url": "https://<r2-host>/watermarked/20260704/<uuid>.pdf",
  "meta": {
    "pages_watermarked": 12,
    "watermark_type": "image",
    "processing_time_ms": 410
  },
  "credits_charged": 1
}

successbooloptional

Always true on 200.

urlstringoptional

Public R2 URL of the watermarked PDF. No expires_at.

metaobjectoptional

pages_watermarked, watermark_type, processing_time_ms.

credits_chargedintoptional

10 authenticated, 0 anonymous. Mirrors X-Credits-Charged.

Examples

curl -X POST https://api.bytefuse.in/api/v1/watermark/image \
  -H "X-API-Key: dt_live_your_key" \
  -F "file=@report.pdf" \
  -F "watermark=@logo.png" \
  -F "position=bottom-right" \
  -F "opacity=0.5" \
  -F "scale=1.0" \
  -F "tile=false"
# Omit the X-API-Key header for the anonymous free-try path.

Errors

422watermark isn’t PNG/JPEG, is empty/corrupt, or opacity/scale out of range; or a corrupt / password-protected PDF.

402 / 429 / 503Insufficient credits (authenticated), rate limited, or capacity/config error.

500The watermark engine failed unexpectedly.

PreviousText Watermark Next OCR