How to Add an Image Watermark to a PDF in Python

Step 1: Prepare the Project

You will need:

• Python 3
• A PDF.co account and API key
• A PDF available through a direct URL
• A watermark image available through a direct URL

Install the Requests library: python -m pip install requests

Store your PDF.co API key in an environment variable named PDFCO_API_KEY.

Step 2: Measure the Watermark Position

Open the source document in the PDF.co PDF Inspector.

Use the Inspector to determine:

• The X coordinate
• The Y coordinate
• The watermark width
• The watermark height
• The pages that should receive the watermark

PDF.co measures coordinates from the top-left corner. Page indexes begin at 0, and 0- represents every page.

Step 3: Add the Python Code

Create a file named app.py and add the following code:

import os
from pathlib import Path

import requests


API_URL = "https://api.pdf.co/v1/pdf/edit/add"
API_KEY = os.environ["PDFCO_API_KEY"]

SOURCE_PDF_URL = "https://example.com/source.pdf"
WATERMARK_IMAGE_URL = "https://example.com/logo.png"
OUTPUT_FILE = Path("watermarked.pdf")


payload = {
    "url": SOURCE_PDF_URL,
    "name": OUTPUT_FILE.name,
    "async": False,
    "images": [
        {
            "url": WATERMARK_IMAGE_URL,
            "x": 400,
            "y": 30,
            "width": 140,
            "height": 60,
            "pages": "0-",
            "keepAspectRatio": True
        }
    ]
}

response = requests.post(
    API_URL,
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    },
    json=payload,
    timeout=60
)

response.raise_for_status()
result = response.json()

if result.get("error"):
    raise RuntimeError(result.get("message", "PDF.co could not process the PDF."))

output_response = requests.get(result["url"], timeout=60)
output_response.raise_for_status()

OUTPUT_FILE.write_bytes(output_response.content)

print(f"Saved watermarked PDF to: {OUTPUT_FILE.resolve()}")

Replace SOURCE_PDF_URL and WATERMARK_IMAGE_URL with direct links to your files.

Step 4: Configure the Watermark

The images object controls the watermark:

• url — direct URL, PDF.co file token, or data URI for the image
• x and y — image position
• width and height — image dimensions
• pages — pages receiving the watermark
• keepAspectRatio — preserves the image’s proportions

For example, use "pages": "0" to watermark only the first page or "pages": "0,2-4" to process selected pages.

See the PDF Add API documentation for all available image settings.

Step 5: Run the Program

Run the script:

python app.py

PDF.co will add the watermark and return a temporary output URL. The script downloads that file and saves it locally as watermarked.pdf.

Open the generated PDF and verify the watermark’s position, size, and page selection. Adjust the coordinates with PDF Inspector if necessary.