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

Headers

Examples

Apply an audio watermark

$
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

$
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"
>
  }'

Apply a video watermark

$
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.

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "JOB_UUID",
5
    "media_type": "audio",
6
    "operation_type": "apply",
7
    "status": "pending",
8
    "model_version": "perth_v2",
9
    "source_media_url": "https://example.com/audio/source.wav",
10
    "metrics": null,
11
    "watermarked_media": null,
12
    "created_at": "2026-07-22T12:00:00.000Z",
13
    "updated_at": "2026-07-22T12:00:00.000Z"
14
  }
15
}

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

$
curl --request GET 'https://app.resemble.ai/api/v2/watermark/apply/JOB_UUID/result' \
>
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Completed response

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "JOB_UUID",
5
    "media_type": "audio",
6
    "operation_type": "apply",
7
    "status": "completed",
8
    "model_version": "perth_v2",
9
    "source_media_url": "https://example.com/audio/source.wav",
10
    "metrics": null,
11
    "watermarked_media": "https://app.resemble.ai/rails/active_storage/...",
12
    "created_at": "2026-07-22T12:00:00.000Z",
13
    "updated_at": "2026-07-22T12:00:04.000Z"
14
  }
15
}

For completed image/video jobs, metrics can also contain the applied strength, custom_message, and payload length.

Response fields

Error handling

Invalid input returns an error response, for example:

1
{
2
  "success": false,
3
  "error": "File must be valid media format"
4
}

The source must be publicly accessible over HTTPS and remain available while processing. Audio and image sources are limited to 25 MB; video sources are limited to 100 MB.