Add image watermark

Overlay an image — a logo, a stamp, a seal — across the pages of a PDF.

At a glance

MCP tool	add_image_watermark
HTTP endpoint	POST /v1/watermark/image
Price	$0.05
Input	One PDF + one image (PNG/JPEG)
Output	The PDF with the image watermark applied to every page

Parameters

Parameter	Type	Required	Description
file	file	yes	Source PDF.
image	file	yes	PNG or JPEG to overlay (URL, upload, or base64).
position	string	no	Placement, e.g. center, top-right, bottom-left. Default center.
opacity	number	no	0–1. Default 0.3.
scale	number	no	Image size relative to the page (e.g. 0.25 = a quarter of page width).

MCP example

Add the logo at https://example.com/logo.png to the bottom-right of every page of https://example.com/invoice.pdf, at 25% size.

{
  "file": "https://example.com/invoice.pdf",
  "image": "https://example.com/logo.png",
  "position": "bottom-right",
  "scale": 0.25,
  "opacity": 0.8
}

HTTP example

curl

curl -i -X POST https://api.pdfasyougo.com/v1/watermark/image \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded-payment-payload>" \
  -d '{"file":"https://example.com/invoice.pdf","image":"https://example.com/logo.png","position":"bottom-right","scale":0.25,"opacity":0.8}'

TypeScript

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.X402_WALLET_PRIVATE_KEY as `0x${string}`);
const fetchWithPay = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPay('https://api.pdfasyougo.com/v1/watermark/image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    file: 'https://example.com/invoice.pdf',
    image: 'https://example.com/logo.png',
    position: 'bottom-right',
    scale: 0.25,
    opacity: 0.8,
  }),
});
console.log((await res.json()).output.url);

Response

{
  "output": {
    "url": "https://files.pdfasyougo.com/o/8f33…?token=…",
    "expires_at": "2026-06-29T12:00:00Z",
    "pages": 3,
    "bytes": 240128
  },
  "operation": "watermark.image",
  "cost": "0.05 USDC"
}

Notes

• Supported image formats: PNG and JPEG. PNG transparency is preserved.
• The watermark is applied to every page.
• To overlay text instead of an image, use Add text watermark.

Note

If the image can’t be fetched or isn’t a PNG/JPEG, the call fails with an input error and isn’t charged.