> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.resemble.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server. # Apply Watermark Apply a Perth v2 watermark to an audio, image, or video file. The media type is automatically detected from the file content. `POST https://app.resemble.ai/api/v2/watermark/apply` ## Request parameters | Field | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | string | Yes | Public HTTPS URL to the audio, image, or video file. | | `output_format` | string | No | `default` returns WAV (audio), PNG (image), or MP4 (video). `source` returns the source's format when it can be reproduced, otherwise the default. Defaults to `default`. See [Output format](/detect/watermark#output-format). | | `strength` | number | No | Image/video watermark strength from 0.0 to 1.0. Defaults to 0.2; ignored for audio. | | `custom_message` | string | No | Image/video message, up to 64 characters. Defaults to `resembleai`; ignored for audio. | ## Headers | Header | Value | Description | | --------------- | ----------------------- | ----------------------------------------------------------------------------------- | | `Authorization` | `Bearer YOUR_API_TOKEN` | Required. Your API token. | | `Content-Type` | `application/json` | Required. | | `Prefer` | `wait` | Optional. Wait for processing and return the completed job in the initial response. | ## Examples ### Apply an audio watermark ```bash curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ --data '{ "url": "https://example.com/audio/source.wav" }' ``` ### Apply an image watermark synchronously ```bash curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Prefer: wait' \ --data '{ "url": "https://example.com/images/photo.png", "strength": 0.2, "custom_message": "resembleai" }' ``` ### Keep the source format ```bash curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ --data '{ "url": "https://example.com/images/photo.jpg", "output_format": "source" }' ``` The completed job's `watermarked_media` URL serves a JPEG. ### Apply a video watermark ```bash curl --request POST 'https://app.resemble.ai/api/v2/watermark/apply' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ --data '{ "url": "https://example.com/videos/clip.mp4", "strength": 0.5 }' ``` ## Initial response Without `Prefer: wait`, the API returns the queued job. All apply jobs report `model_version` as `perth_v2`. ```json { "success": true, "item": { "uuid": "JOB_UUID", "media_type": "audio", "operation_type": "apply", "status": "pending", "model_version": "perth_v2", "source_media_url": "https://example.com/audio/source.wav", "metrics": null, "watermarked_media": null, "created_at": "2026-07-22T12:00:00.000Z", "updated_at": "2026-07-22T12:00:00.000Z" } } ``` With `Prefer: wait`, the same shape is returned after processing. On success, `status` is `completed` and `watermarked_media` contains a signed download URL. ## Fetch apply result Retrieve the current state of an apply job using its UUID. `GET https://app.resemble.ai/api/v2/watermark/apply/{uuid}/result` ```bash curl --request GET 'https://app.resemble.ai/api/v2/watermark/apply/JOB_UUID/result' \ -H 'Authorization: Bearer YOUR_API_TOKEN' ``` ### Completed response ```json { "success": true, "item": { "uuid": "JOB_UUID", "media_type": "audio", "operation_type": "apply", "status": "completed", "model_version": "perth_v2", "source_media_url": "https://example.com/audio/source.wav", "metrics": null, "watermarked_media": "https://app.resemble.ai/rails/active_storage/...", "created_at": "2026-07-22T12:00:00.000Z", "updated_at": "2026-07-22T12:00:04.000Z" } } ``` For completed image/video jobs, `metrics` can also contain the applied `strength`, `custom_message`, and payload length. ### Response fields | Field | Type | Description | | ------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------- | | `success` | boolean | Whether the API request succeeded. | | `item.uuid` | string | Unique identifier for the watermark job. | | `item.media_type` | string | Detected media type: `audio`, `image`, or `video`. | | `item.operation_type` | string | `apply`. | | `item.status` | string | `pending`, `processing`, `completed`, or `failed`. | | `item.model_version` | string | `perth_v2`. | | `item.source_media_url` | string | Original source URL. | | `item.watermarked_media` | string \| null | Signed output URL when complete; otherwise `null`. The file is WAV, PNG, or MP4 unless `output_format` was `source`. | | `item.metrics` | object \| null | Apply metadata when available. | | `item.created_at` | string | Job creation timestamp. | | `item.updated_at` | string | Job update timestamp. | > **Warning** > > The signed `watermarked_media` URL expires. Download and store the asset promptly. ## Error handling Invalid input returns an error response, for example: ```json { "success": false, "error": "File must be valid media format" } ``` An `output_format` other than `default` or `source` is rejected with `output_format must be one of source, default`. The source must be publicly accessible over HTTPS and remain available while processing. Audio, image, and video sources are limited to 200 MB.