Safety & DetectionWatermarking

Detect Watermark

Beta: Watermark API is currently in beta. Please contact us if you would like to be added to the beta program.

Detect a watermark in an audio, image, or video file using the provided URL. The media type is automatically detected from the file content.

POST https://app.resemble.ai/api/v2/watermark/detect

Request Parameters

FieldTypeRequiredDescription
urlstring✅HTTPS URL to the media file (audio, image, or video).
custom_messagestring❌Custom message used during encoding for image/video (default: “resembleai”). Ignored for audio.

Headers

HeaderValueDescription
AuthorizationBearer YOUR_API_TOKENRequired. Your API token.
Content-Typeapplication/jsonRequired.
PreferwaitOptional. When set, the API processes synchronously and returns the completed result with metrics.

Examples

Audio

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/detect' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/audio/suspect.wav"
>  }'

Image (synchronous)

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/detect' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  -H 'Prefer: wait' \
>  --data '{
>    "url": "https://example.com/images/suspect.png",
>    "custom_message": "resembleai"
>  }'

Video

$curl --request POST 'https://app.resemble.ai/api/v2/watermark/detect' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/videos/suspect.mp4"
>  }'

Response

1{
2  "success": true,
3  "item": {
4    "uuid": "JOB_UUID",
5    "media_type": "image",
6    "source_media_url": "https://example.com/images/suspect.png",
7    "metrics": null,
8    "watermarked_media": null,
9    "created_at": "2024-01-01T00:00:00.000Z",
10    "updated_at": "2024-01-01T00:00:00.000Z"
11  }
12}

When the Prefer: wait header is set, metrics will be populated in the initial response. Without the header, processing is asynchronous and you must poll the result endpoint.

Fetch Watermark Detection Result

Retrieve the result of a detected watermark using the provided UUID.

GET https://app.resemble.ai/api/v2/watermark/detect/{uuid}/result

Example

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

Audio Detection Response

1{
2  "success": true,
3  "item": {
4    "uuid": "JOB_UUID",
5    "media_type": "audio",
6    "source_media_url": "https://example.com/audio/suspect.wav",
7    "metrics": {
8      "has_watermark": {
9        "channel_0": true,
10        "channel_1": true
11      }
12    },
13    "watermarked_media": null,
14    "created_at": "2024-01-01T00:00:00.000Z",
15    "updated_at": "2024-01-01T00:00:00.000Z"
16  }
17}

Image/Video Detection Response

1{
2  "success": true,
3  "item": {
4    "uuid": "JOB_UUID",
5    "media_type": "image",
6    "source_media_url": "https://example.com/images/suspect.png",
7    "metrics": {
8      "has_watermark": true
9    },
10    "watermarked_media": null,
11    "created_at": "2024-01-01T00:00:00.000Z",
12    "updated_at": "2024-01-01T00:00:00.000Z"
13  }
14}

Response Fields

FieldTypeDescription
successbooleanIndicates whether the operation was successful.
item.uuidstringUnique identifier for the watermark job.
item.media_typestringDetected media type: audio, image, or video.
item.source_media_urlstringThe original source URL provided in the request.
item.metricsobjectDetection results. null while processing.
item.metrics.has_watermarkobject | booleanFor audio: an object with per-channel results (e.g., channel_0, channel_1). For image/video: a boolean.
item.created_atstringTimestamp of when the job was created.
item.updated_atstringTimestamp of when the job was last updated.

Error Handling

If the request is unsuccessful, you will receive an error response:

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

Ensure that you provide a valid HTTPS URL pointing to a supported media file.