# Watermark API

Watermark, resize and convert images, videos and PDFs over HTTP. Send a public file URL and a list of operations; the API processes the file in the background and gives you a link to the result.

## How a request works

1. `POST` a source URL and operations to a processing endpoint. The API answers `202 Accepted` with a request in status `queued`.
2. Poll `GET /v1/requests/{id}` until it is `succeeded`, `failed` or `aborted`, or pass `webhook_url` to have it posted to you.
3. Download `result.files[0].url`. Failed and aborted requests are free.

```bash
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"},
    "customer": "cus_42"
  }'
```

## Endpoints

| Endpoint | What it does | Price |
| --- | --- | --- |
| [`POST /v1/images/process`](https://api.watermark.ws/docs/reference.md#process-image) | Process image. | $0.002 per request |
| [`POST /v1/images/read`](https://api.watermark.ws/docs/reference.md#read-image) | Read image. | $0.0005 per request |
| [`POST /v1/videos/process`](https://api.watermark.ws/docs/reference.md#process-video) | Process video. | $0.02 per started minute of video, accounts that have bought credits only |
| [`POST /v1/videos/read`](https://api.watermark.ws/docs/reference.md#read-video) | Read video. | $0.001 per request, accounts that have bought credits only |
| [`POST /v1/videos/screenshot`](https://api.watermark.ws/docs/reference.md#screenshot-video) | Screenshot video. | $0.002 per request, accounts that have bought credits only |
| [`POST /v1/documents/process`](https://api.watermark.ws/docs/reference.md#process-document) | Process document. | $0.004 per page |
| [`POST /v1/documents/read`](https://api.watermark.ws/docs/reference.md#read-document) | Read document. | $0.0005 per request |
| [`POST /v1/documents/snapshot`](https://api.watermark.ws/docs/reference.md#snapshot-document) | Snapshot document. | $0.002 per request |
| [`GET /v1/requests`](https://api.watermark.ws/docs/reference.md#list-requests) | List requests. | free |
| [`GET /v1/requests/{id}`](https://api.watermark.ws/docs/reference.md#get-request) | Get request. | free |
| [`GET /v1/results/{id}`](https://api.watermark.ws/docs/reference.md#download-result) | Download result. | free |
| [`POST /v1/requests/{id}/abort`](https://api.watermark.ws/docs/reference.md#abort-request) | Abort request. | free |
| [`GET /v1/account`](https://api.watermark.ws/docs/reference.md#get-account) | Get account. | free |
| [`GET /v1/usage`](https://api.watermark.ws/docs/reference.md#get-usage) | Get usage. | free |
| [`GET /v1/operations`](https://api.watermark.ws/docs/reference.md#list-operations) | List operations. | free |

## Operations

| Operation | Images | Videos | PDFs | What it does |
| --- | --- | --- | --- | --- |
| [`watermark`](https://api.watermark.ws/docs/operations.md#watermark) | yes | yes | yes | Place an image (a logo, usually a transparent PNG) over the file, at its own size. Resize the watermark image beforehand. |
| [`border`](https://api.watermark.ws/docs/operations.md#border) | yes | yes |  | Add a border of a color on each side. |
| [`resize`](https://api.watermark.ws/docs/operations.md#resize) | yes | yes |  | Resize to a width and height. |
| [`crop`](https://api.watermark.ws/docs/operations.md#crop) | yes | yes |  | Cut out a rectangle. |
| [`thumbnail`](https://api.watermark.ws/docs/operations.md#thumbnail) | yes |  |  | Make a small, fast-loading copy, metadata stripped. |
| [`rotate`](https://api.watermark.ws/docs/operations.md#rotate) | yes | yes |  | Rotate by degrees, clockwise, and optionally mirror. |
| [`flip`](https://api.watermark.ws/docs/operations.md#flip) | yes | yes |  | Mirror the file. |
| [`orient`](https://api.watermark.ws/docs/operations.md#orient) | yes |  |  | Turn the image upright from its EXIF orientation. |
| [`grayscale`](https://api.watermark.ws/docs/operations.md#grayscale) | yes | yes |  | Remove the color. |
| [`sepia`](https://api.watermark.ws/docs/operations.md#sepia) | yes |  |  | Give the image a sepia tone. |
| [`exposure`](https://api.watermark.ws/docs/operations.md#exposure) | yes |  |  | Adjust brightness and contrast. |
| [`filter`](https://api.watermark.ws/docs/operations.md#filter) | yes |  |  | Apply a photo filter. |
| [`remove_background`](https://api.watermark.ws/docs/operations.md#remove_background) | yes |  |  | Make the background color transparent (output PNG or WebP to keep it). |
| [`compress`](https://api.watermark.ws/docs/operations.md#compress) | yes |  |  | Re-encode at a quality, 1-100. |

## Libraries

- PHP: `composer require watermark/watermark-php`. See [PHP library](https://api.watermark.ws/docs/php.md).
- Command line: `npm install -g @watermark/cli`, or `brew install watermarkws/tap/watermark`. See [Command line](https://api.watermark.ws/docs/cli.md).
- Any other language: JSON over HTTP, as in the [API reference](https://api.watermark.ws/docs/reference.md), which shows every call with curl, PHP and the CLI.

## Docs

- [Quickstart](https://api.watermark.ws/docs/quickstart.md)
- [Authentication](https://api.watermark.ws/docs/authentication.md)
- [Requests, results and retries](https://api.watermark.ws/docs/requests.md)
- [Webhooks](https://api.watermark.ws/docs/webhooks.md)
- [Errors](https://api.watermark.ws/docs/errors.md)
- [PHP library](https://api.watermark.ws/docs/php.md)
- [Command line](https://api.watermark.ws/docs/cli.md)
- [Pricing and limits](https://api.watermark.ws/docs/pricing.md)
- [Operations](https://api.watermark.ws/docs/operations.md)
- [API reference](https://api.watermark.ws/docs/reference.md)

## Machine-readable

- [llms.txt](https://api.watermark.ws/llms.txt), and every page in one file: [llms-full.txt](https://api.watermark.ws/llms-full.txt)
- [OpenAPI 3.1 spec](https://api.watermark.ws/openapi.json)
- [Prices and limits as JSON](https://api.watermark.ws/pricing.json)
- Any docs page as Markdown: add `.md` to its URL, or send `Accept: text/markdown`.