Watermark API
For AI agents Get an API key
Libraries

Command line

View as Markdown

Install it with npm or Homebrew, or run it once with npx.

The watermark command runs the Watermark API from a terminal, a shell script or a CI job. It waits for each request, downloads the result, and with --json prints output that scripts and AI agents can read.

Install

Run it once without installing anything (Node.js 18 or newer):

Shell 
npx @watermark/cli --version

Or install it, so watermark is on your path:

Shell 
npm install -g @watermark/cli

On macOS or Linux with Homebrew:

Shell 
brew install watermarkws/tap/watermark

It has no dependencies besides Node.js. Check the install with watermark --version.

Set your key

Create a key at watermark.ws/developers and export it. A wm_test_… key is free and returns real results.

Shell 
export WATERMARK_API_KEY=wm_test_…

--api-key on a single command works too, but leaves the key in your shell history.

Watermark an image

Terminal 
$ watermark image process https://example.com/photo.jpg \
    --op resize:width=1600,height=1600 \
    --op watermark:image_url=https://example.com/logo.png,x=40,y=40 \
    --format webp --out photo.webp
Request 1234 (images/process): succeeded
Result: {"width":1600,"height":1067,"format":"WEBP","size":183021}
File: https://… (link valid until 2026-10-18T15:00:04Z)
Saved to photo.webp
Price: $0.002000

The command waits for the request to finish (up to --timeout, 300 seconds), and --out downloads the result. The source must be a public http or https URL.

Operations

Each --op is one operation, and they run in the order you give them:

--op type:param=value,param=value

Numbers and true/false are sent as such; everything else as text. For anything awkward to write that way, pass the whole list as JSON:

Shell 
watermark image process https://example.com/photo.jpg \
  --ops-json '[{"type":"filter","name":"nashville","strength":50},{"type":"compress","quality":70}]'

watermark operations image (or video, document) lists every operation and its parameters, read live from the API. The Operations page shows each with a picture.

More examples

Watermark every page of a PDF

Shell 
watermark document process https://example.com/contract.pdf \
  --op watermark:image_url=https://example.com/logo.png,x=148,y=712,diagonal_lines_color=#c0392b,diagonal_lines_opacity=35 \
  --out contract-watermarked.pdf

Watermark the first minute of a video

Terminal 
$ watermark video process https://example.com/clip.mp4 \
    --op resize:width=1280,height=720 \
    --op watermark:image_url=https://example.com/logo.png,x=32,y=32 \
    --max-duration 60 --out clip.mp4
Request 1240: processing 45%

Video requests report their progress while they run.

Save one frame, or one page

Shell 
watermark video screenshot https://example.com/clip.mp4 --seconds 3 --out poster.jpg
watermark document snapshot https://example.com/contract.pdf --page 1 --format png --out page-1.png

Start now, collect later

Shell 
watermark image process https://example.com/photo.jpg --op grayscale --no-wait --json | jq .id
watermark request get 1234

A whole list of files

Shell 
mkdir -p out
while read -r url; do
  watermark image process "$url" \
    --op watermark:image_url=https://example.com/logo.png,x=40,y=40 \
    --customer cus_42 --out "out/$(basename "$url")"
done < urls.txt

Read a file's details in a script

Shell 
width=$(watermark image read https://example.com/photo.jpg --json | jq '.result.data.width')

For scripts and AI agents

  • --json prints the request exactly as the API returns it, and nothing else on stdout. Progress goes to stderr.
  • The exit code says what happened:
Code Meaning
0 Succeeded (or queued, with --no-wait).
1 The API refused the call, or the request failed or was aborted. The error code is printed.
2 The command was used wrongly.
  • Rate limits and server errors are retried twice with the same Idempotency-Key. Pass --idempotency-key to make a retry of the whole command safe too.

Commands

watermark image process <url> --op <operation> [--op ...] [--format webp] [--out file]
watermark image read <url>
watermark video process <url> --op <operation> [--max-duration 30] [--out file]
watermark video read <url>
watermark video screenshot <url> --seconds 5 [--format png] [--out file]
watermark document process <url> --op <operation> [--max-pages 10] [--out file]
watermark document read <url>
watermark document snapshot <url> [--page 1] [--format png] [--out file]
watermark request get <id>
watermark request abort <id>
watermark requests [--limit 20]
watermark account
watermark usage [--from 2026-10-01] [--to 2026-10-31] [--group-by day|endpoint|customer|status]
watermark operations [image|video|document]
Option What it does
--out <file> Wait, then download the result to this file.
--no-wait Return as soon as the request is queued.
--timeout <seconds> How long to wait. Default 300.
--format <format> The output format, such as webp or png.
--webhook <url> Post the finished request here.
--customer <id> Your own reference for who the request is for.
--metadata key=value Repeatable. Returned with the request.
--idempotency-key <key> Make a retry of this command safe.
--json Print JSON only.
--api-key <key> Or set WATERMARK_API_KEY.
--base-url <url> Or set WATERMARK_API_URL. Default https://api.watermark.ws.

Source

MIT licensed, on GitHub at watermarkws/watermark-cli.