{ "openapi": "3.1.0", "info": { "title": "Watermark API", "version": "1.0.0", "summary": "Watermark, resize and convert images, videos and PDFs.", "description": "Send a URL and a list of operations; the API processes the file in the background and returns a link to the result.\n\nEvery processing endpoint answers `202` with a request in status `queued`. Poll `GET /v1/requests/{id}` or pass `webhook_url`.\n\n**[See every operation, with the request to send and a picture of the result](https://api.watermark.ws/docs/operations)**\n\nDocs: https://api.watermark.ws/docs · As Markdown, for AI agents: https://api.watermark.ws/llms.txt", "contact": { "name": "Watermark support", "email": "support@watermark.ws", "url": "https://watermark.ws/developers" } }, "servers": [ { "url": "https://api.watermark.ws" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Images", "description": "JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC and AVIF in; JPEG, PNG, WebP, GIF or TIFF out." }, { "name": "Videos", "description": "MP4, MOV, WebM, MKV, AVI, FLV, MPEG and MPEG-TS in; MP4 out. Needs an account that has bought credits." }, { "name": "Documents", "description": "PDF in and out." }, { "name": "Requests", "description": "Follow, list and abort requests." }, { "name": "Account", "description": "Balance, usage and the operation catalog." } ], "paths": { "/v1/images/process": { "post": { "tags": [ "Images" ], "summary": "Process image", "description": "Run operations on an image, in order, and save the result.\n\nPrice: $0.002 per request. Failed requests are free.", "operationId": "processImage", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageProcessRequest" }, "examples": { "watermark-corner": { "summary": "Watermark: A logo in the bottom-right corner", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 552, "y": 524 } ] } }, "watermark-tiled": { "summary": "Watermark: Repeated across the whole photo", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 40, "y": 36, "tile_spacing_x": 440, "tile_spacing_y": 140 } ] } }, "border": { "summary": "Border: A white frame, wider at the bottom", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "border", "top": 24, "bottom": 72, "left": 24, "right": 24, "color": "#ffffff" } ] } }, "resize-fit": { "summary": "Resize: Fit inside 450 × 450", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "resize", "width": 450, "height": 450 } ] } }, "resize-fill": { "summary": "Resize: Fill a 400 × 400 square", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "resize", "width": 400, "height": 400, "crop_center": true } ] } }, "crop": { "summary": "Crop: A 400 × 400 square from the right side", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "crop", "x": 470, "y": 130, "width": 400, "height": 400 } ] } }, "thumbnail": { "summary": "Thumbnail: 300 pixels wide, quality 70", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "thumbnail", "width": 300, "quality": 70 } ] } }, "rotate": { "summary": "Rotate: A quarter turn clockwise", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "rotate", "degrees": 90 } ] } }, "flip": { "summary": "Flip: Mirrored left to right", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "flip", "horizontal": true } ] } }, "orient": { "summary": "Orient: A phone photo stored sideways, turned upright", "value": { "source": "https://example.com/phone-photo.jpg", "operations": [ { "type": "orient" } ] } }, "grayscale": { "summary": "Grayscale: Black and white", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "grayscale" } ] } }, "sepia": { "summary": "Sepia: Threshold 80", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "sepia", "threshold": 80 } ] } }, "exposure": { "summary": "Exposure: Brighter, with more contrast", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "exposure", "brightness": 10, "contrast": 45 } ] } }, "filter-toaster": { "summary": "Filter: Toaster", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "filter", "name": "toaster" } ] } }, "filter-nashville": { "summary": "Filter: Nashville at half strength", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "filter", "name": "nashville", "strength": 50 } ] } }, "remove-background": { "summary": "Remove background: A signature lifted off the paper", "value": { "source": "https://example.com/signature.jpg", "operations": [ { "type": "remove_background", "tolerance": 20, "blur": 1 } ], "output": { "format": "png" } } }, "compress": { "summary": "Compress: Quality 40", "value": { "source": "https://example.com/photo.jpg", "operations": [ { "type": "compress", "quality": 40 } ] } } } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "images/process", "status": "queued", "livemode": true, "source": "https://example.com/photo.jpg", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/images/read": { "post": { "tags": [ "Images" ], "summary": "Read image", "description": "Read dimensions, format, colorspace and orientation.\n\nPrice: $0.0005 per request. Failed requests are free.", "operationId": "readImage", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadRequest" }, "example": { "source": "https://example.com/photo.jpg" } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "images/read", "status": "queued", "livemode": true, "source": "https://example.com/photo.jpg", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/videos/process": { "post": { "tags": [ "Videos" ], "summary": "Process video", "description": "Run operations on a video, in order, and save an MP4. Reports `progress` while it runs.\n\nPrice: $0.02 per started minute of video (accounts that have bought credits only). Failed requests are free.", "operationId": "processVideo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoProcessRequest" }, "examples": { "watermark-corner": { "summary": "Watermark: A logo in the bottom-right corner", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 552, "y": 524 } ] } }, "watermark-tiled": { "summary": "Watermark: Repeated across the whole video", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 40, "y": 36, "tile_spacing_x": 440, "tile_spacing_y": 140 } ] } }, "border": { "summary": "Border: A white frame, wider at the bottom", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "border", "top": 24, "bottom": 72, "left": 24, "right": 24, "color": "#ffffff" } ] } }, "resize-fit": { "summary": "Resize: Fit inside 450 × 450", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "resize", "width": 450, "height": 450 } ] } }, "resize-fill": { "summary": "Resize: Fill a 400 × 400 square", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "resize", "width": 400, "height": 400, "crop_center": true } ] } }, "crop": { "summary": "Crop: A 400 × 400 square from the right side", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "crop", "x": 470, "y": 130, "width": 400, "height": 400 } ] } }, "rotate": { "summary": "Rotate: A quarter turn clockwise", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "rotate", "degrees": 90 } ] } }, "flip": { "summary": "Flip: Mirrored left to right", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "flip", "horizontal": true } ] } }, "grayscale": { "summary": "Grayscale: Black and white", "value": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "grayscale" } ] } } } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "videos/process", "status": "queued", "livemode": true, "source": "https://example.com/clip.mp4", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/videos/read": { "post": { "tags": [ "Videos" ], "summary": "Read video", "description": "Read dimensions, duration, codec, bitrate and frame rate.\n\nPrice: $0.001 per request (accounts that have bought credits only). Failed requests are free.", "operationId": "readVideo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadRequest" }, "example": { "source": "https://example.com/clip.mp4" } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "videos/read", "status": "queued", "livemode": true, "source": "https://example.com/clip.mp4", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/videos/screenshot": { "post": { "tags": [ "Videos" ], "summary": "Screenshot video", "description": "Save one frame as an image.\n\nPrice: $0.002 per request (accounts that have bought credits only). Failed requests are free.", "operationId": "screenshotVideo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenshotRequest" } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "videos/screenshot", "status": "queued", "livemode": true, "source": "https://example.com/clip.mp4", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/documents/process": { "post": { "tags": [ "Documents" ], "summary": "Process document", "description": "Run operations on every page of a PDF.\n\nPrice: $0.004 per page. Failed requests are free.", "operationId": "processDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentProcessRequest" }, "examples": { "watermark-pdf": { "summary": "Watermark: On every page of a PDF, with diagonal lines", "value": { "source": "https://example.com/contract.pdf", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 148, "y": 712, "diagonal_lines_color": "#c0392b", "diagonal_lines_opacity": 35 } ] } } } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "documents/process", "status": "queued", "livemode": true, "source": "https://example.com/contract.pdf", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/documents/read": { "post": { "tags": [ "Documents" ], "summary": "Read document", "description": "Read the page count and page size.\n\nPrice: $0.0005 per request. Failed requests are free.", "operationId": "readDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadRequest" }, "example": { "source": "https://example.com/contract.pdf" } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "documents/read", "status": "queued", "livemode": true, "source": "https://example.com/contract.pdf", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/documents/snapshot": { "post": { "tags": [ "Documents" ], "summary": "Snapshot document", "description": "Render one page as an image.\n\nPrice: $0.002 per request. Failed requests are free.", "operationId": "snapshotDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotRequest" } } } }, "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1234, "object": "request", "endpoint": "documents/snapshot", "status": "queued", "livemode": true, "source": "https://example.com/contract.pdf", "created_at": "2026-10-11T15:00:00Z" } } } }, "200": { "description": "The request first sent with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/requests": { "get": { "tags": [ "Requests" ], "summary": "List requests", "description": "The account's requests, newest first.", "operationId": "listRequests", "parameters": [ { "name": "limit", "in": "query", "description": "How many requests to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "before", "in": "query", "description": "Only requests older than this id. Pass the last id of a page to get the next one.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A page of requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestList" } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/requests/{id}": { "get": { "tags": [ "Requests" ], "summary": "Get request", "description": "One request, with its result once it has succeeded. Download links in the result work until the result is deleted.", "operationId": "getRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id.", "schema": { "type": "integer" }, "example": 1234 } ], "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/results/{id}": { "get": { "tags": [ "Requests" ], "summary": "Download result", "description": "The link in `result.files[].url`: open it as given, with no key. It works until the result is deleted (`url_expires_at`) and redirects to the file. Anyone with the link can download the file.", "operationId": "downloadResult", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id.", "schema": { "type": "integer" }, "example": 1234 }, { "name": "expires", "in": "query", "required": true, "description": "Part of the link.", "schema": { "type": "integer" }, "example": 1792335604 }, { "name": "signature", "in": "query", "required": true, "description": "Part of the link.", "schema": { "type": "string" }, "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } ], "responses": { "302": { "description": "Redirects to the file.", "headers": { "Location": { "schema": { "type": "string" } } } }, "403": { "description": "The link is not valid, or has expired (`link_invalid`)." }, "410": { "description": "The result has been deleted (`result_deleted`)." } } } }, "/v1/requests/{id}/abort": { "post": { "tags": [ "Requests" ], "summary": "Abort request", "description": "Stop a request that has not finished. It is not charged.", "operationId": "abortRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id.", "schema": { "type": "integer" }, "example": 1235 } ], "responses": { "200": { "description": "The aborted request. One that has already finished is a `409 request_finished`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "id": 1235, "object": "request", "endpoint": "videos/process", "status": "aborted", "livemode": true, "source": "https://example.com/clip.mp4", "price": { "amount": "0.000000", "currency": "usd", "micro_usd": 0 }, "created_at": "2026-10-11T15:00:00Z", "completed_at": "2026-10-11T15:00:09Z" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get account", "description": "The account behind the key: balance, tier, and the key's mode and limits.", "operationId": "getAccount", "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/usage": { "get": { "tags": [ "Account" ], "summary": "Get usage", "description": "Requests, spend and bytes over at most 92 days, grouped by day, endpoint, customer or status.", "operationId": "getUsage", "parameters": [ { "name": "from", "in": "query", "description": "First day, `YYYY-MM-DD`. Defaults to 29 days ago.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "to", "in": "query", "description": "Last day, `YYYY-MM-DD`. Defaults to today.", "schema": { "type": "string", "format": "date" } }, { "name": "group_by", "in": "query", "description": "What each row totals.", "schema": { "type": "string", "enum": [ "day", "endpoint", "customer", "status" ], "default": "day" }, "example": "endpoint" }, { "name": "customer", "in": "query", "description": "Only this customer's requests.", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v1/operations": { "get": { "tags": [ "Account" ], "summary": "List operations", "description": "Every operation, its parameters and the output formats, per media type: what a client needs to build requests. The same catalog, with pictures, is at https://api.watermark.ws/docs/operations.", "operationId": "listOperations", "responses": { "200": { "description": "The catalog. The example shows one operation of one media type.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "operations", "data": { "image": { "formats": [ "jpg", "png", "webp", "gif", "tif" ], "operations": { "resize": { "description": "Resize to a width and height.", "params": { "width": { "description": "The width in pixels.", "required": true }, "height": { "description": "The height in pixels.", "required": true }, "preserve_aspect_ratio": { "description": "Fit inside the box instead of stretching to it.", "required": false, "default": true }, "crop_center": { "description": "Fill the box and crop what overflows, centered.", "required": false, "default": false } } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } } }, "webhooks": { "request.succeeded": { "post": { "summary": "request.succeeded", "operationId": "requestSucceeded", "description": "A request finished with a result. Signed in the `Watermark-Signature` header: `t=,v1=.\" with your webhook secret>`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried 3 times." } } } }, "request.failed": { "post": { "summary": "request.failed", "operationId": "requestFailed", "description": "A request finished without a result; it is not charged. Signed in the `Watermark-Signature` header: `t=,v1=.\" with your webhook secret>`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried 3 times." } } } }, "request.aborted": { "post": { "summary": "request.aborted", "operationId": "requestAborted", "description": "A request was aborted. Signed in the `Watermark-Signature` header: `t=,v1=.\" with your webhook secret>`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried 3 times." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key: `wm_live_…` (charged) or `wm_test_…` (free, limited)." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a retry safe: the same key with the same body returns the first request instead of starting another.", "schema": { "type": "string", "maxLength": 255 } } }, "schemas": { "ImageOperationResize": { "type": "object", "title": "resize", "description": "Resize to a width and height.", "required": [ "type", "width", "height" ], "properties": { "type": { "type": "string", "const": "resize" }, "width": { "description": "The width in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "The height in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "preserve_aspect_ratio": { "description": "Fit inside the box instead of stretching to it.", "type": "boolean", "default": true }, "crop_center": { "description": "Fill the box and crop what overflows, centered.", "type": "boolean", "default": false } }, "additionalProperties": false }, "ImageOperationCrop": { "type": "object", "title": "crop", "description": "Cut out a rectangle.", "required": [ "type", "x", "y", "width", "height" ], "properties": { "type": { "type": "string", "const": "crop" }, "x": { "description": "Left edge in pixels.", "type": "integer", "minimum": 0, "maximum": 20000 }, "y": { "description": "Top edge in pixels.", "type": "integer", "minimum": 0, "maximum": 20000 }, "width": { "description": "The width in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "The height in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 } }, "additionalProperties": false }, "ImageOperationRotate": { "type": "object", "title": "rotate", "description": "Rotate by degrees, clockwise, and optionally mirror.", "required": [ "type", "degrees" ], "properties": { "type": { "type": "string", "const": "rotate" }, "degrees": { "description": "Degrees clockwise.", "type": "integer", "minimum": -360, "maximum": 360 }, "flip_horizontal": { "description": "Mirror left to right.", "type": "boolean", "default": false }, "flip_vertical": { "description": "Mirror top to bottom.", "type": "boolean", "default": false } }, "additionalProperties": false }, "ImageOperationFlip": { "type": "object", "title": "flip", "description": "Mirror the file.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "flip" }, "horizontal": { "description": "Mirror left to right.", "type": "boolean", "default": false }, "vertical": { "description": "Mirror top to bottom.", "type": "boolean", "default": false } }, "additionalProperties": false }, "ImageOperationGrayscale": { "type": "object", "title": "grayscale", "description": "Remove the color.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "grayscale" } }, "additionalProperties": false }, "ImageOperationBorder": { "type": "object", "title": "border", "description": "Add a border of a color on each side.", "required": [ "type", "top", "bottom", "left", "right", "color" ], "properties": { "type": { "type": "string", "const": "border" }, "top": { "description": "Top border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "bottom": { "description": "Bottom border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "left": { "description": "Left border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "right": { "description": "Right border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "color": { "description": "The border color. A hex color, such as \"#ffffff\".", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, "ImageOperationWatermark": { "type": "object", "title": "watermark", "description": "Place an image (a logo, usually a transparent PNG) over the file, at its own size. Resize the watermark image beforehand.", "required": [ "type", "image_url", "x", "y" ], "properties": { "type": { "type": "string", "const": "watermark" }, "image_url": { "description": "URL of the watermark image (JPEG, PNG, GIF or WebP).", "type": "string", "maxLength": 2048, "format": "uri" }, "x": { "description": "The x position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "y": { "description": "The y position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "tile_spacing_x": { "description": "Repeat the watermark across the file: the step in pixels from one copy's left edge to the next (with tile_spacing_y).", "type": "number", "minimum": 0, "maximum": 20000 }, "tile_spacing_y": { "description": "When tiling, the step in pixels from one copy's top edge to the next.", "type": "number", "minimum": 0, "maximum": 20000 }, "diagonal_lines_color": { "description": "Also draw two diagonal lines corner to corner in this color. A hex color, such as \"#ffffff\".", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$" }, "diagonal_lines_opacity": { "description": "Opacity of the diagonal lines, 0-100.", "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "ImageOperationThumbnail": { "type": "object", "title": "thumbnail", "description": "Make a small, fast-loading copy, metadata stripped.", "required": [ "type", "width" ], "properties": { "type": { "type": "string", "const": "thumbnail" }, "width": { "description": "The width in pixels.", "type": "integer", "minimum": 1, "maximum": 4000 }, "height": { "description": "The height in pixels; kept in proportion when left out.", "type": "integer", "minimum": 1, "maximum": 4000 }, "quality": { "description": "Compression quality, 1-100.", "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "ImageOperationCompress": { "type": "object", "title": "compress", "description": "Re-encode at a quality, 1-100.", "required": [ "type", "quality" ], "properties": { "type": { "type": "string", "const": "compress" }, "quality": { "description": "Compression quality, 1-100.", "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "ImageOperationSepia": { "type": "object", "title": "sepia", "description": "Give the image a sepia tone.", "required": [ "type", "threshold" ], "properties": { "type": { "type": "string", "const": "sepia" }, "threshold": { "description": "How strong the tone is, 0-100.", "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "ImageOperationExposure": { "type": "object", "title": "exposure", "description": "Adjust brightness and contrast.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "exposure" }, "brightness": { "description": "From -100 to 100.", "type": "integer", "minimum": -100, "maximum": 100, "default": 0 }, "contrast": { "description": "From -100 to 100.", "type": "integer", "minimum": -100, "maximum": 100, "default": 0 } }, "additionalProperties": false }, "ImageOperationFilter": { "type": "object", "title": "filter", "description": "Apply a photo filter.", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "const": "filter" }, "name": { "description": "One of: amaro, apollo, brannan, earlybird, gotham, hefe, inkwell, kelvin, lomo, nashville, poprocket, rise, sierra, toaster, valencia, walden, willow, xpro2.", "type": "string", "enum": [ "amaro", "apollo", "brannan", "earlybird", "gotham", "hefe", "inkwell", "kelvin", "lomo", "nashville", "poprocket", "rise", "sierra", "toaster", "valencia", "walden", "willow", "xpro2" ] }, "strength": { "description": "How much of the look, 0-100.", "type": "integer", "minimum": 0, "maximum": 100, "default": 100 } }, "additionalProperties": false }, "ImageOperationRemoveBackground": { "type": "object", "title": "remove_background", "description": "Make the background color transparent (output PNG or WebP to keep it).", "required": [ "type", "tolerance" ], "properties": { "type": { "type": "string", "const": "remove_background" }, "tolerance": { "description": "How far from the background color still counts as background, 0-100.", "type": "integer", "minimum": 0, "maximum": 100 }, "blur": { "description": "Soften the cut edge, 0-10.", "type": "integer", "minimum": 0, "maximum": 10, "default": 0 } }, "additionalProperties": false }, "ImageOperationOrient": { "type": "object", "title": "orient", "description": "Turn the image upright from its EXIF orientation.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "orient" } }, "additionalProperties": false }, "ImageOperation": { "description": "One image operation; `type` picks which.", "oneOf": [ { "$ref": "#/components/schemas/ImageOperationResize" }, { "$ref": "#/components/schemas/ImageOperationCrop" }, { "$ref": "#/components/schemas/ImageOperationRotate" }, { "$ref": "#/components/schemas/ImageOperationFlip" }, { "$ref": "#/components/schemas/ImageOperationGrayscale" }, { "$ref": "#/components/schemas/ImageOperationBorder" }, { "$ref": "#/components/schemas/ImageOperationWatermark" }, { "$ref": "#/components/schemas/ImageOperationThumbnail" }, { "$ref": "#/components/schemas/ImageOperationCompress" }, { "$ref": "#/components/schemas/ImageOperationSepia" }, { "$ref": "#/components/schemas/ImageOperationExposure" }, { "$ref": "#/components/schemas/ImageOperationFilter" }, { "$ref": "#/components/schemas/ImageOperationRemoveBackground" }, { "$ref": "#/components/schemas/ImageOperationOrient" } ], "discriminator": { "propertyName": "type", "mapping": { "resize": "#/components/schemas/ImageOperationResize", "crop": "#/components/schemas/ImageOperationCrop", "rotate": "#/components/schemas/ImageOperationRotate", "flip": "#/components/schemas/ImageOperationFlip", "grayscale": "#/components/schemas/ImageOperationGrayscale", "border": "#/components/schemas/ImageOperationBorder", "watermark": "#/components/schemas/ImageOperationWatermark", "thumbnail": "#/components/schemas/ImageOperationThumbnail", "compress": "#/components/schemas/ImageOperationCompress", "sepia": "#/components/schemas/ImageOperationSepia", "exposure": "#/components/schemas/ImageOperationExposure", "filter": "#/components/schemas/ImageOperationFilter", "remove_background": "#/components/schemas/ImageOperationRemoveBackground", "orient": "#/components/schemas/ImageOperationOrient" } } }, "VideoOperationResize": { "type": "object", "title": "resize", "description": "Resize to a width and height.", "required": [ "type", "width", "height" ], "properties": { "type": { "type": "string", "const": "resize" }, "width": { "description": "The width in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "The height in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "preserve_aspect_ratio": { "description": "Fit inside the box instead of stretching to it.", "type": "boolean", "default": true }, "crop_center": { "description": "Fill the box and crop what overflows, centered.", "type": "boolean", "default": false } }, "additionalProperties": false }, "VideoOperationCrop": { "type": "object", "title": "crop", "description": "Cut out a rectangle.", "required": [ "type", "x", "y", "width", "height" ], "properties": { "type": { "type": "string", "const": "crop" }, "x": { "description": "Left edge in pixels.", "type": "integer", "minimum": 0, "maximum": 20000 }, "y": { "description": "Top edge in pixels.", "type": "integer", "minimum": 0, "maximum": 20000 }, "width": { "description": "The width in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 }, "height": { "description": "The height in pixels.", "type": "integer", "minimum": 1, "maximum": 20000 } }, "additionalProperties": false }, "VideoOperationRotate": { "type": "object", "title": "rotate", "description": "Rotate by degrees, clockwise, and optionally mirror.", "required": [ "type", "degrees" ], "properties": { "type": { "type": "string", "const": "rotate" }, "degrees": { "description": "Degrees clockwise.", "type": "integer", "minimum": -360, "maximum": 360 }, "flip_horizontal": { "description": "Mirror left to right.", "type": "boolean", "default": false }, "flip_vertical": { "description": "Mirror top to bottom.", "type": "boolean", "default": false } }, "additionalProperties": false }, "VideoOperationFlip": { "type": "object", "title": "flip", "description": "Mirror the file.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "flip" }, "horizontal": { "description": "Mirror left to right.", "type": "boolean", "default": false }, "vertical": { "description": "Mirror top to bottom.", "type": "boolean", "default": false } }, "additionalProperties": false }, "VideoOperationGrayscale": { "type": "object", "title": "grayscale", "description": "Remove the color.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "grayscale" } }, "additionalProperties": false }, "VideoOperationBorder": { "type": "object", "title": "border", "description": "Add a border of a color on each side.", "required": [ "type", "top", "bottom", "left", "right", "color" ], "properties": { "type": { "type": "string", "const": "border" }, "top": { "description": "Top border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "bottom": { "description": "Bottom border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "left": { "description": "Left border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "right": { "description": "Right border in pixels.", "type": "integer", "minimum": 0, "maximum": 2000 }, "color": { "description": "The border color. A hex color, such as \"#ffffff\".", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, "VideoOperationWatermark": { "type": "object", "title": "watermark", "description": "Place an image (a logo, usually a transparent PNG) over the file, at its own size. Resize the watermark image beforehand.", "required": [ "type", "image_url", "x", "y" ], "properties": { "type": { "type": "string", "const": "watermark" }, "image_url": { "description": "URL of the watermark image (JPEG, PNG, GIF or WebP).", "type": "string", "maxLength": 2048, "format": "uri" }, "x": { "description": "The x position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "y": { "description": "The y position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "tile_spacing_x": { "description": "Repeat the watermark across the file: the step in pixels from one copy's left edge to the next (with tile_spacing_y).", "type": "number", "minimum": 0, "maximum": 20000 }, "tile_spacing_y": { "description": "When tiling, the step in pixels from one copy's top edge to the next.", "type": "number", "minimum": 0, "maximum": 20000 }, "diagonal_lines_color": { "description": "Also draw two diagonal lines corner to corner in this color. A hex color, such as \"#ffffff\".", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$" }, "diagonal_lines_opacity": { "description": "Opacity of the diagonal lines, 0-100.", "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "VideoOperation": { "description": "One video operation; `type` picks which.", "oneOf": [ { "$ref": "#/components/schemas/VideoOperationResize" }, { "$ref": "#/components/schemas/VideoOperationCrop" }, { "$ref": "#/components/schemas/VideoOperationRotate" }, { "$ref": "#/components/schemas/VideoOperationFlip" }, { "$ref": "#/components/schemas/VideoOperationGrayscale" }, { "$ref": "#/components/schemas/VideoOperationBorder" }, { "$ref": "#/components/schemas/VideoOperationWatermark" } ], "discriminator": { "propertyName": "type", "mapping": { "resize": "#/components/schemas/VideoOperationResize", "crop": "#/components/schemas/VideoOperationCrop", "rotate": "#/components/schemas/VideoOperationRotate", "flip": "#/components/schemas/VideoOperationFlip", "grayscale": "#/components/schemas/VideoOperationGrayscale", "border": "#/components/schemas/VideoOperationBorder", "watermark": "#/components/schemas/VideoOperationWatermark" } } }, "DocumentOperationWatermark": { "type": "object", "title": "watermark", "description": "Place an image over every page.", "required": [ "type", "image_url", "x", "y" ], "properties": { "type": { "type": "string", "const": "watermark" }, "image_url": { "description": "URL of the watermark image (JPEG, PNG, GIF or WebP).", "type": "string", "maxLength": 2048, "format": "uri" }, "x": { "description": "The x position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "y": { "description": "The y position in pixels, from the top left.", "type": "integer", "minimum": -20000, "maximum": 20000 }, "tile_spacing_x": { "description": "Repeat the watermark across the file: the step in pixels from one copy's left edge to the next (with tile_spacing_y).", "type": "number", "minimum": 0, "maximum": 20000 }, "tile_spacing_y": { "description": "When tiling, the step in pixels from one copy's top edge to the next.", "type": "number", "minimum": 0, "maximum": 20000 }, "diagonal_lines_color": { "description": "Also draw two diagonal lines corner to corner in this color. A hex color, such as \"#ffffff\".", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$" }, "diagonal_lines_opacity": { "description": "Opacity of the diagonal lines, 0-100.", "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "DocumentOperation": { "description": "One document operation; `type` picks which.", "oneOf": [ { "$ref": "#/components/schemas/DocumentOperationWatermark" } ], "discriminator": { "propertyName": "type", "mapping": { "watermark": "#/components/schemas/DocumentOperationWatermark" } } }, "ImageProcessRequest": { "type": "object", "required": [ "source", "operations" ], "example": { "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" }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "operations": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/ImageOperation" }, "description": "Run in order, top to bottom. Each is `{\"type\": …}` plus that operation's parameters. See [Operations](https://api.watermark.ws/docs/operations.md)." }, "output": { "type": "object", "description": "How to save the result.", "properties": { "format": { "type": "string", "enum": [ "jpg", "png", "webp", "gif", "tif" ], "default": "jpg", "description": "The file format of the result." } }, "additionalProperties": false }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "VideoProcessRequest": { "type": "object", "required": [ "source", "operations" ], "example": { "source": "https://example.com/clip.mp4", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 24, "y": 24 } ], "webhook_url": "https://example.com/hooks/watermark" }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "operations": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/VideoOperation" }, "description": "Run in order, top to bottom. Each is `{\"type\": …}` plus that operation's parameters. See [Operations](https://api.watermark.ws/docs/operations.md)." }, "output": { "type": "object", "description": "How to save the result.", "properties": { "format": { "type": "string", "enum": [ "mp4" ], "default": "mp4", "description": "The file format of the result." } }, "additionalProperties": false }, "max_duration": { "type": "integer", "minimum": 1, "maximum": 7200, "description": "Only keep the first this many seconds." }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "DocumentProcessRequest": { "type": "object", "required": [ "source", "operations" ], "example": { "source": "https://example.com/contract.pdf", "operations": [ { "type": "watermark", "image_url": "https://example.com/logo.png", "x": 36, "y": 36, "diagonal_lines_color": "#c0c0c0", "diagonal_lines_opacity": 40 } ] }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "operations": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/DocumentOperation" }, "description": "Run in order, top to bottom. Each is `{\"type\": …}` plus that operation's parameters. See [Operations](https://api.watermark.ws/docs/operations.md)." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 2000, "description": "Only keep the first this many pages." }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "ReadRequest": { "type": "object", "required": [ "source" ], "example": { "source": "https://example.com/photo.jpg" }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "ScreenshotRequest": { "type": "object", "required": [ "source", "seconds" ], "example": { "source": "https://example.com/clip.mp4", "seconds": 5, "output": { "format": "jpg" } }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "seconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Which moment, in seconds from the start." }, "output": { "type": "object", "description": "How to save the result.", "properties": { "format": { "type": "string", "enum": [ "jpg", "png" ], "default": "jpg", "description": "The file format of the result." } }, "additionalProperties": false }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "SnapshotRequest": { "type": "object", "required": [ "source" ], "example": { "source": "https://example.com/contract.pdf", "page": 1, "output": { "format": "png" } }, "properties": { "source": { "type": "string", "format": "uri", "maxLength": 2048, "description": "A public `http` or `https` URL of the file. See [Sources](https://api.watermark.ws/docs/requests.md#sources)." }, "page": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 1, "description": "Which page, from 1." }, "output": { "type": "object", "description": "How to save the result.", "properties": { "format": { "type": "string", "enum": [ "jpg", "png" ], "default": "jpg", "description": "The file format of the result." } }, "additionalProperties": false }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Where to post the request when it finishes. Defaults to the account's webhook, if set. See [Webhooks](https://api.watermark.ws/docs/webhooks.md)." }, "customer": { "type": "string", "maxLength": 64, "description": "Your own reference for who the request is for. Returned with it, and totalled by `GET /v1/usage?group_by=customer`." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": [ "string", "number", "boolean" ], "maxLength": 255 }, "description": "Up to 20 keys of your own, returned with the request and in its webhooks." } } }, "Request": { "type": "object", "required": [ "id", "object", "endpoint", "status", "livemode", "created_at" ], "example": { "id": 1234, "object": "request", "endpoint": "images/process", "status": "succeeded", "livemode": true, "source": "https://example.com/photo.jpg", "result": { "data": { "width": 1600, "height": 1067, "format": "WEBP", "size": 183021 }, "files": [ { "url": "https://api.watermark.ws/v1/results/1234?expires=1792335604&signature=…", "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 }, "customer": "cus_42", "created_at": "2026-10-11T15:00:00Z", "completed_at": "2026-10-11T15:00:04Z" }, "properties": { "id": { "type": "integer", "description": "The request's id." }, "object": { "type": "string", "const": "request", "description": "Always `request`." }, "endpoint": { "type": "string", "examples": [ "images/process" ], "description": "Which endpoint started it, such as `images/process`." }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "aborted" ], "description": "Where the request is. Only `succeeded` is charged." }, "livemode": { "type": "boolean", "description": "`false` for a test key's request." }, "source": { "type": "string", "description": "The URL the file was downloaded from." }, "input": { "type": "object", "description": "What was sent besides the source: operations, output and the endpoint's own fields." }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How far a video has got while it is processing." }, "result": { "type": "object", "description": "Once succeeded.", "properties": { "data": { "type": "object", "description": "About the output: dimensions and format for images, duration and codec for videos, pages and size for PDFs." }, "files": { "type": "array", "description": "The files made. Read endpoints make none.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "A signed link to download the file." }, "url_expires_at": { "type": "string", "format": "date-time", "description": "When the link stops working: when the result is deleted." }, "format": { "type": "string", "description": "The file format, such as `webp`." }, "size": { "type": [ "integer", "null" ], "description": "Bytes." } } } }, "deleted_at": { "type": "string", "format": "date-time", "description": "When the files are deleted, 7 days after the request finished." } } }, "error": { "type": "object", "description": "Once failed. See [Errors](https://api.watermark.ws/docs/errors.md#a-request-that-fails-while-processing).", "properties": { "code": { "type": "string", "description": "Stable; branch on it." }, "message": { "type": "string", "description": "For people." } } }, "price": { "$ref": "#/components/schemas/Money" }, "customer": { "type": "string", "description": "As sent." }, "metadata": { "type": "object", "description": "As sent." }, "created_at": { "type": "string", "format": "date-time", "description": "When the request was accepted." }, "completed_at": { "type": "string", "format": "date-time", "description": "When it finished." } } }, "RequestList": { "type": "object", "example": { "object": "list", "data": [ { "id": 1234, "object": "request", "endpoint": "images/process", "status": "succeeded", "livemode": true, "created_at": "2026-10-11T15:00:00Z" } ], "has_more": true }, "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Request" } }, "has_more": { "type": "boolean" } } }, "Money": { "type": "object", "description": "An amount of money.", "properties": { "amount": { "type": "string", "description": "Dollars, six decimals.", "examples": [ "0.002000" ] }, "currency": { "type": "string", "const": "usd", "description": "Always `usd`." }, "micro_usd": { "type": "integer", "description": "Millionths of a dollar." } } }, "Account": { "type": "object", "example": { "object": "account", "id": 7, "name": "Acme Photos", "email": "dev@example.com", "tier": "paid", "balance": { "amount": "18.420000", "currency": "usd", "micro_usd": 18420000 }, "webhook_url": "https://example.com/hooks/watermark", "livemode": true, "limits": { "requests_per_minute": 120, "concurrent_requests": 10, "max_source_bytes": 2147483648 }, "suspended": false, "created_at": "2026-10-11T14:52:10Z" }, "properties": { "object": { "type": "string", "const": "account" }, "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "tier": { "type": "string", "enum": [ "free", "paid" ] }, "balance": { "$ref": "#/components/schemas/Money" }, "webhook_url": { "type": "string" }, "livemode": { "type": "boolean" }, "limits": { "type": "object", "properties": { "requests_per_minute": { "type": "integer" }, "concurrent_requests": { "type": "integer", "description": "How many of the account's requests may be queued or processing at once." }, "max_source_bytes": { "type": "integer" }, "requests_per_day": { "type": "integer", "description": "Test keys only." } } }, "suspended": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Usage": { "type": "object", "example": { "object": "usage", "from": "2026-10-01", "to": "2026-10-13", "group_by": "endpoint", "data": [ { "endpoint": "images/process", "requests": 1840, "succeeded": 1822, "failed": 18, "spent": "3.644000", "spent_micro_usd": 3644000, "source_bytes": 912455120, "result_bytes": 301228873 } ] }, "properties": { "object": { "type": "string", "const": "usage" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "group_by": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "spent": { "type": "string" }, "spent_micro_usd": { "type": "integer" }, "source_bytes": { "type": "integer" }, "result_bytes": { "type": "integer" } }, "additionalProperties": true } } } }, "Event": { "type": "object", "example": { "id": "evt_1234_done", "object": "event", "type": "request.succeeded", "created": 1791738000, "data": { "id": 1234, "object": "request", "status": "succeeded", "result": { "…": "…" } } }, "properties": { "id": { "type": "string", "description": "The same on every retry of a delivery. Use it to ignore a repeat." }, "object": { "type": "string", "const": "event", "description": "Always `event`." }, "type": { "type": "string", "enum": [ "request.succeeded", "request.failed", "request.aborted" ], "description": "What happened." }, "created": { "type": "integer", "description": "Unix time." }, "data": { "$ref": "#/components/schemas/Request" } } }, "Error": { "type": "object", "required": [ "error" ], "example": { "error": { "type": "invalid_request", "code": "validation_failed", "message": "The operations.0.width field must be between 1 and 20000.", "param": "operations.0.width", "request_id": "1234" } }, "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication", "permission", "payment_required", "not_found", "conflict", "rate_limited", "server_error" ] }, "code": { "type": "string", "description": "Stable; branch on it." }, "message": { "type": "string", "description": "For people." }, "param": { "type": "string", "description": "The input the error is about." }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "Every invalid field, for a validation error." } } } } } }, "responses": { "401": { "description": "No key, or not a valid one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No credit left, or the endpoint needs an account that has paid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A conflict: the request has finished, or the Idempotency-Key was used for another request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input, or a URL the API will not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests a minute (rate_limited, see Retry-After), or too many of the account's requests running at once (concurrency_limited).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }