Watermark API — Free Tier + Pay-As-You-Go
Add a text or image watermark to PDFs, videos, and images via API. Nine anchor positions, opacity, size, and colour.
What it does
The Watermark API is `POST /v1/convert` with one of three operations: `add-watermark-pdf`, `add-watermark-image` or `add-watermark-video`. A text mark is described by `watermarkText` plus `watermarkPosition`, `watermarkOpacity` (5-100), `watermarkFontSize` (8-200) and `watermarkColor` as a hex value. Positions are the nine standard anchors — `top-left`, `top-center`, `top-right`, `middle-left`, `center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right` — validated at the request schema, so a typo is a 400 rather than a silently misplaced mark.
Defaults differ per engine: PDFs and images centre the mark at 30% opacity, video places it bottom-right at 50%. For an image mark instead of text, send the overlay as an extra `additionalFile` part next to the source file; the endpoint accepts PNG, JPEG, WebP, GIF, BMP and TIFF overlays, and PDF specifically needs a PNG or JPEG because that is what can be embedded. Each engine composites differently — pdf-lib draws on every page in Helvetica, Sharp composites onto images with full alpha handling, and video renders the mark to a PNG that FFmpeg's overlay filter burns into the frames, which means watermarking a video always re-encodes it.
Not supported: user-controlled rotation, tiled or repeating marks, uploaded custom fonts, explicit pixel coordinates, and page- or time-range scoping.
Supported formats
Source formats (10)
- mp4
- mov
- mkv
- webm
- jpg
- png
- webp
- tiff
- gif
Target formats (7)
- mp4
- mov
- jpg
- png
- webp
- tiff
Quick start
Every sample posts the job, then polls /v1/status/{jobId} until it finishes, with your API key in the X-Api-Key header. The parameter names below are the ones the endpoint actually accepts — anything else is dropped rather than rejected.
curl -X POST https://api.convertintomp4.com/v1/convert \
-H "X-Api-Key: ck_your_api_key" \
-F "file=@input.pdf" \
-F "targetFormat=pdf" \
-F "toolOperation=add-watermark-pdf" \
-F "watermarkText=DRAFT" \
-F "watermarkPosition=center" \
-F "watermarkOpacity=30"import { readFileSync } from "node:fs";
import { ConvertIntoMP4Client } from "convertintomp4";
const apiKey = process.env.CIM4_API_KEY;
const client = new ConvertIntoMP4Client({ apiKey });
// watermarkOpacity is 5-100; watermarkFontSize is 8-200
const { jobId } = await client.uploadDirect(
readFileSync("input.pdf"),
"input.pdf",
"application/pdf",
{
targetFormat: "pdf",
toolOperation: "add-watermark-pdf",
watermarkText: "DRAFT",
watermarkPosition: "center",
watermarkOpacity: 30,
watermarkColor: "#888888",
},
);
let job;
do {
await new Promise((r) => setTimeout(r, 2000));
job = await fetch(`https://api.convertintomp4.com/v1/status/${jobId}`, {
headers: { "X-Api-Key": apiKey },
}).then((r) => r.json());
} while (job.status !== "completed" && job.status !== "failed");
console.log("Watermarked:", job.result?.downloadUrl);import time, requests
api_key = "ck_your_api_key"
# An image watermark rides along as an extra "additionalFile" part.
job = requests.post(
"https://api.convertintomp4.com/v1/convert",
headers={"X-Api-Key": api_key},
files={
"file": ("input.jpg", open("input.jpg", "rb"), "image/jpeg"),
"additionalFile": ("logo.png", open("logo.png", "rb"), "image/png"),
},
data={
"targetFormat": "jpg",
"toolOperation": "add-watermark-image",
"watermarkPosition": "bottom-right",
"watermarkOpacity": "40",
},
).json()
while True:
status = requests.get(
f"https://api.convertintomp4.com/v1/status/{job['jobId']}",
headers={"X-Api-Key": api_key},
).json()
if status["status"] in ("completed", "failed"):
break
time.sleep(2)
print("Watermarked:", status.get("result", {}).get("downloadUrl"))Features
- Three operations: `add-watermark-pdf`, `add-watermark-image`, `add-watermark-video`
- Text marks via `watermarkText` with hex colour, 8-200 font size and 5-100 opacity
- Image marks by sending the overlay as an `additionalFile` part (PNG, JPEG, WebP, GIF, BMP, TIFF)
- Nine anchor positions, validated at the request schema so a typo returns a 400
- pdf-lib for PDFs, Sharp compositing for images, FFmpeg overlay burn-in for video
- Applied to every page and every frame — there is no page or time scoping
Pricing
From $9.99/mo (Pro) or $24.99/mo (Business) — or pay-as-you-go on the API plan.
Free tier: 5 conversions/day, 100 MB file size, no API key required (IP-gated). Pro $9.99/mo: 100/day (2,000/month), 2 GB files. Business $24.99/mo: 1,000/day (20,000/month), 10 GB files, GPU encoding, dedicated support.
See full pricing breakdown →Built for production
99.9% uptime SLA
Multi-region failover, transparent status page, 60-second response-time guarantee on Business.
Encryption + auto-delete
TLS 1.2+ in transit, AES-256 at rest. Files deleted after 1h / 24h / 7d depending on plan, or instantly via DELETE endpoint. See the security page.
~7s median latency
Most sub-100 MB jobs complete in 6-9 seconds. Webhook-driven async for heavier workloads; waitForJob for synchronous flows.
Frequently Asked Questions
How precisely can I position the watermark?
To one of nine named anchors via `watermarkPosition` — the corners, the edge midpoints and the centre. There are no explicit pixel or point coordinates for watermarking. Defaults are `center` at 30% opacity for PDFs and images and `bottom-right` at 50% for video, so a request with only `watermarkText` still produces a sensible result.
Can I rotate or tile the watermark?
No. There is no rotation parameter and no repeating-grid mode; a single mark is drawn at the anchor you choose. The one exception is cosmetic and not configurable: a PDF text watermark placed at `center` is drawn on a fixed 45-degree diagonal, which is the conventional look for a DRAFT stamp.
Can I use a custom font for text watermarks?
No. PDF text marks are drawn in Helvetica, and image and video marks are rendered from the fonts bundled in the processing image. There is no font upload field, and a `fontFamily` parameter would be ignored rather than rejected. What you can control is size, colour, opacity and position.
How do I use a logo instead of text?
Send the source as the `file` part and the logo as an `additionalFile` part in the same multipart request, then omit `watermarkText`. Overlay files must be images — PNG, JPEG, WebP, GIF, BMP or TIFF — and anything else returns a 400 before the job is queued. For PDF targets use PNG or JPEG specifically, since those are the formats that can be embedded into the page. PNG alpha is respected.
Does watermarking a video re-encode it?
Yes, always. The mark is rendered to a PNG and composited into the frames with FFmpeg's overlay filter, so the output is a full re-encode and the watermark lives in the pixel data — it survives downstream re-encoding, screenshots and screen recording. There is no stream-copy or separate-track watermarking mode.
Related APIs
- Compression APICompress video, image, PDF, and audio files programmatically. Quality presets, resolution scaling, and a real byte-ceiling mode for video and audio.
- Merge APIMerge PDFs, videos, images, and audio files programmatically. Upload-order concatenation with per-type engines.
- Split APIPull a page range out of a PDF or cut a time range out of a video or audio file via API. One output per request.
- OCR APIOptical character recognition for scanned PDFs and images via API. Tesseract, searchable-PDF or plain-text output, 17 language packs.
- File Conversion APIOne unified file conversion API for video, audio, image, document, ebook, archive, and font formats — 255 formats, 2,290+ conversion pairs.
- Convert APIProduction-grade file conversion API with 9 language SDKs, async webhooks, and cloud-to-cloud workflows. Free tier available.
Or browse the full catalogue of 23 API products →
Get an API key
Start integrating the Watermark API in five minutes. Read the docs, grab a key, and ship your first conversion before the trial coffee cools.