# Quickstart

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](https://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

```bash
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](https://api.watermark.ws/docs/php.md) or the [command line](https://api.watermark.ws/docs/cli.md) 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](https://api.watermark.ws/docs/webhooks.md)).

```bash
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

- Every operation, its parameters and a picture of its result: [Operations](https://api.watermark.ws/docs/operations.md), or `GET /v1/operations`.
- Every endpoint, field and response: the [API reference](https://api.watermark.ws/docs/reference.md).
- Prices and limits: [Pricing and limits](https://api.watermark.ws/docs/pricing.md).
- Machine-readable: the [OpenAPI spec](https://api.watermark.ws/openapi.json), and [llms.txt](https://api.watermark.ws/llms.txt) for AI agents. Add `.md` to any docs URL for its Markdown.