Watermark API · v1

Watermark, resize and convert files over HTTP

Send a file's URL and a list of operations. The API processes the image, video or PDF in the background and hands you a link to the result.

Start with the quickstart See every operation

$1.00 free credit $0.002 per image Test keys are free

curl -X POST https://api.watermark.ws/v1/images/process \
  -H "Authorization: Bearer $WATERMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://example.com/photo.jpg",
    "operations": [
      {"type": "resize", "width": 1600, "height": 1600},
      {"type": "watermark", "image_url": "https://example.com/logo.png", "x": 40, "y": 40}
    ],
    "output": {"format": "webp"}
  }'

$client = new \Watermark\Api\Client(getenv('WATERMARK_API_KEY'));

$request = $client->images->process('https://example.com/photo.jpg', [
    ['type' => 'resize', 'width' => 1600, 'height' => 1600],
    ['type' => 'watermark', 'image_url' => 'https://example.com/logo.png', 'x' => 40, 'y' => 40],
], [
    'output' => ['format' => 'webp'],
]);

# Waits for the result; add --no-wait to return as soon as it is queued.
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-watermarked.webp

const response = await fetch('https://api.watermark.ws/v1/images/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WATERMARK_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "source": "https://example.com/photo.jpg",
    "operations": [
      {"type": "resize", "width": 1600, "height": 1600},
      {"type": "watermark", "image_url": "https://example.com/logo.png", "x": 40, "y": 40}
    ],
    "output": {"format": "webp"}
  }),
});

const request = await response.json(); // { id: 1234, status: 'queued', … }

import os, requests

request = requests.post(
    "https://api.watermark.ws/v1/images/process",
    headers={"Authorization": f"Bearer {os.environ['WATERMARK_API_KEY']}"},
    json={
      "source": "https://example.com/photo.jpg",
      "operations": [
        {"type": "resize", "width": 1600, "height": 1600},
        {"type": "watermark", "image_url": "https://example.com/logo.png", "x": 40, "y": 40}
      ],
      "output": {"format": "webp"}
    },
).json()  # {"id": 1234, "status": "queued", …}

How a request works

Every processing endpoint follows the same three steps, whatever the file.

Requests and results →

POST /v1/images/process

Send a URL and operations

The API checks the request and answers at once with 202 Accepted.

{ "id": 1234, "status": "queued" }

GET /v1/requests/1234

It runs in the background

Poll the request, or pass webhook_url and get it posted to you when it finishes.

queuedprocessingsucceededfailedaborted

result.files[0].url

Download the result

Follow the link in the finished request. Failed and aborted requests are free.

"format": "webp", "size": 183021

What you can do

Operations chain in one request: resize, then watermark, then save as WebP.

Full API reference →

Images14 operations

Watermark, resize, crop, filter, cut out a background, and convert between JPG, PNG, WebP, GIF and TIFF.

watermark border resize crop thumbnail rotate flip orient grayscale sepia exposure filter remove_background compress

Videos7 operations

Watermark every frame, resize, crop and rotate, saved as MP4. Or save one frame as an image.

watermark border resize crop rotate flip grayscale

PDFs1 operation

Stamp a logo on every page, with diagonal lines if you like. Or render one page as an image.

watermark

Libraries

Call the API from PHP or a terminal. Both wait for the result and retry safely; any other language works over plain HTTP.

PHP library Every endpoint as a method, typed errors and webhook checks. PHP 8.1 or newer. composer require watermark/watermark-php Command line For scripts, CI jobs and AI agents: --json output and exit codes that mean something. npm install -g @watermark/cli Any language JSON over HTTP. Every endpoint in the reference has cURL, PHP and CLI examples, and the OpenAPI spec generates clients. https://api.watermark.ws/openapi.json

Docs

Guides explain how the API behaves. The reference lists every field.

Quickstart Get a key, start a request, download the result. /docs/quickstart Operations Every operation, each with a request and a picture of its result. /docs/operations API reference Every endpoint, parameter, response and status code. /docs/reference Requests, results and retries Statuses, results, sources, idempotency and your own references. /docs/requests Webhooks Events, retries, and checking the signature in PHP, Node.js and Python. /docs/webhooks Errors The error shape and every code, with what to do about it. /docs/errors

Pricing

Prepaid credit. Failed and aborted requests are free, and so is everything run with a test key.

Pricing and limits →

$1.00

Free credit on a new account

$0.002 / image

images/process

$0.004 / page

documents/process

$0.02 / minute

videos/process, accounts that have bought credits

For AI agents

Every page is also Markdown

Add .md to any docs URL, or ask for text/markdown, and you get the page as plain Markdown that reads well in a terminal or a model's context.

/llms.txtAn index of every page /llms-full.txtEvery page in one file /openapi.jsonOpenAPI 3.1 spec /pricing.jsonPrices and limits, no key needed

Two ways to the same Markdown

curl https://api.watermark.ws/docs/webhooks.md

curl https://api.watermark.ws/docs/webhooks \
  -H "Accept: text/markdown"