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.

{
  "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

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

Completed response

{
  "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

Error handling

Invalid input returns an error response, for example:

{
  "success": false,
  "error": "File must be valid media format"
}

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.