---
title: "Detect watermark"
method: POST
path: "/watermark/detect"
tags: ["watermark"]
---

# Detect watermark

`POST /watermark/detect`

Detect a watermark in an audio, image, or video file. Audio runs Perth v1 and Perth v2 concurrently; image/video is publicly reported as Perth v2. Processing is asynchronous unless the `Prefer: wait` header is supplied.

## Headers

- `Authorization` string, required
- `Prefer` 'wait'

## Request body

- WatermarkDetectRequest
  - `url` string, uri, required — Public HTTPS URL to the audio, image, or video source.
  - `custom_message` string — Message used when applying the image/video watermark. Ignored for audio.

## Response `200`

Detection job created

- WatermarkDetectResponse
  - `success` boolean, required
  - `item` WatermarkDetectItem, required
    - `uuid` string, required
    - `media_type` 'audio' | 'image' | 'video', required
    - `operation_type` 'detect', required
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required
    - `model_version` 'perth_v2' — Present for image/video. Audio versions are reported in metrics.model_results.
    - `source_media_url` string, uri, required
    - `metrics` union — Null while processing. New results use the media-specific versioned schema; historical audio results can use a flat shape.
      - WatermarkAudioDetectionMetrics
        - `overall_status` 'present' | 'absent' | 'inconclusive', required
        - `detected_model_versions` WatermarkAudioDetectionMetricsDetectedModelVersionsItems[], required — Only model versions that positively detected a watermark.
        - `coverage_complete` boolean, required — True only when both audio detectors completed successfully.
        - `has_watermark` object, required — Per-channel aggregate across successful audio detectors.
        - `confidence` number, double, nullable
        - `model_results` WatermarkAudioModelResult[], required
          - `model_version` 'perth_v1' | 'perth_v2', required
          - `status` 'succeeded' | 'failed', required
          - `detected` boolean, nullable, required — Null when this detector was unavailable.
          - `has_watermark` object — Successful per-channel detection results.
          - `confidence` number, double, nullable
          - `error` string — Safe error message when status is failed.
      - WatermarkVisionDetectionMetrics
        - `overall_status` 'present' | 'degraded' | 'absent' | 'inconclusive', required
        - `detected_model_versions` WatermarkVisionDetectionMetricsDetectedModelVersionsItems[], required — Contains perth_v2 only when watermark signal is detected.
        - `has_watermark` boolean, required
        - `detection_score` number, double, nullable, required
        - `model_results` WatermarkVisionModelResult[], required
          - `model_version` 'perth_v2', required
          - `status` 'succeeded', required
          - `detected` boolean, required
          - `confidence` number, double, nullable
        - `verdict` 'verified' | 'degraded' | 'not_watermarked' — Backward-compatible image/video verdict.
        - `synthid` boolean — Optional auxiliary SynthID signal for images.
    - `watermarked_media` string, uri, nullable — Detection does not produce output media.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Changes

> 6 revisions in range; 3 could not be searched.

- **2026-07-26** `5e92bebbaf1f` — 2 breaking, 11 info
  - added `#/components/schemas/WatermarkDetectItemMetrics` to the `item/metrics` response property `oneOf` list for the response status `200`
  - the `item/watermarked_media` response's property type/format changed from `string, null`/`` to `string, null`/`uri` for status `200`
  - added the optional property `item/model_version` to the response with the `200` status
  - the response property `item` became required for the status `200`
  - …9 more

[Change history](https://skmtc.dev/resemble/apis/api-reference/changes/watermark/detect/post.md)

---

[API](https://skmtc.dev/resemble/apis/api-reference.md) · [All operations](https://skmtc.dev/resemble/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/resemble/api-reference/revisions/e93597a6b425/schema)