Watermark API
For AI agents Get an API key
Get started

Quickstart

View as Markdown

Watermark a photo in three calls: get a key, start a request, download the result.

The Watermark API watermarks, resizes and converts images, videos and PDFs. You send a URL and a list of operations; the API fetches the file, processes it in the background and gives you a link to the result.

1. Get a key

Sign in at watermark.ws/developers, open an account and create a key. Keys start with wm_live_ (charged) or wm_test_ (free, with small limits). A new account comes with free credit to try the API.

2. Start a request

Shell 
curl 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"}
  }'

Using PHP or a terminal? The same call with the PHP library or the command line also waits for the result for you.

The API answers 202 Accepted with the request, which is queued:

JSON 
{"id": 1234, "object": "request", "endpoint": "images/process", "status": "queued", "livemode": true, "created_at": "2026-10-11T15:00:00Z"}

3. Get the result

Poll the request until its status is succeeded, failed or aborted, or pass webhook_url and the API posts the request to you when it finishes (see Webhooks).

Shell 
curl https://api.watermark.ws/v1/requests/1234 -H "Authorization: Bearer $WATERMARK_API_KEY"
JSON 
{
  "id": 1234,
  "status": "succeeded",
  "result": {
    "data": {"width": 1600, "height": 1067, "format": "WEBP"},
    "files": [{"url": "https://…", "url_expires_at": "2026-10-18T15:00:04Z", "format": "webp", "size": 183021}],
    "deleted_at": "2026-10-18T15:00:04Z"
  },
  "price": {"amount": "0.002000", "currency": "usd", "micro_usd": 2000}
}

Download result.files[0].url. The link works until the result is deleted, 7 days after the request finished.

What next