API reference

Detect a watermark

Detect watermark API reference: send an image, read the watermark Etchv finds, and match its watermark ID to your records. Up to 95 MB and 40 MP.

POST/watermarks/images/detect
Upload
95 MB · 192 MB via upload
Output
Detection JSON
CPU cost
1 credit / file

Request

Use a key with watermarks:detect. Send the image file as the multipart file field.

Shell
curl --fail-with-body https://api.etchv.com/watermarks/images/detect \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -F 'file=@watermarked.png'

Response

Returns 200 JSON and an X-Request-ID header. Compare the watermark_id it found with the watermark ID you saved when you embedded the file.

FieldMeaning
watermarkedThe same watermark was found in every frame, page or combined layer image
watermark_idRecovered 64-character hex ID, or null
confidenceHow certain the read was, from 0 to 1, taken from the least certain unit
unitsFor each frame or page (unit): index, watermarked, confidence and watermark_id; indexes start at zero
copyWith links:read, or signed in to the dashboard: present when the watermark is on a copy one of your traceable links made: asset_id (the copy), link (id, name), recipient (the email it was made for) and opened_at (when they first opened the link, or null)
assetWith assets:read, or signed in to the dashboard: present when the watermark is on another of your watermarked assets: asset_id, name, metadata and created_at
watermarked
Meaning
The same watermark was found in every frame, page or combined layer image
watermark_id
Meaning
Recovered 64-character hex ID, or null
confidence
Meaning
How certain the read was, from 0 to 1, taken from the least certain unit
units
Meaning
For each frame or page (unit): index, watermarked, confidence and watermark_id; indexes start at zero
copy
Meaning
With links:read, or signed in to the dashboard: present when the watermark is on a copy one of your traceable links made: asset_id (the copy), link (id, name), recipient (the email it was made for) and opened_at (when they first opened the link, or null)
asset
Meaning
With assets:read, or signed in to the dashboard: present when the watermark is on another of your watermarked assets: asset_id, name, metadata and created_at
JSON
{
  "watermarked": true,
  "watermark_id": "9f2c…",
  "confidence": 0.98,
  "copy": {
    "asset_id": "ast_…",
    "link": { "id": "lnk_…", "name": "Q3 board deck" },
    "recipient": "alice@acme.com",
    "opened_at": "2026-10-03T14:22:05Z"
  }
}

Interpret the result

  • Watermark matches: copy names the recipient a traceable link made it for, and asset names the asset in your library. Otherwise, look up the watermark ID in your own records.
  • Watermark in only some units, or different watermarks: check units. The top-level result is watermarked: false with a null watermark_id.
  • No watermark found: the detection still completed and is billed. It does not tell you whether an image is AI-generated.

High confidence does not guarantee the exact watermark is recovered after edits. A match identifies a copy, not who shared it. Detection does not return your original JSON or create an asset-library record. Only your Organization’s own copies and assets are ever named, and only to a key or app that may read them.

Recovery from edited or photographed copies

A watermark ID is 256 bits. Etchv compares the watermark it reads with the ones it issued and still keeps on your Organization’s watermarked assets. If one differs by 48 bits or fewer, Etchv returns that issued watermark ID. Only your Organization’s records are compared. Otherwise it returns the watermark it read, which may match no record. Test the edits your workflow produces.

Send a request again

If a response never arrives (a dropped connection, for example), send the same request again with the same Idempotency-Key header (8–128 letters, digits, - or _). A resend with the same key and the same file is never charged again.

SituationResponse
Default (keep_result omitted or true)The first request’s result, kept for 24 hours, with the same X-Request-ID and Idempotent-Replayed: true
keep_result=false on the first requestNothing is kept, so the file is detected again, free, up to 5 times within 24 hours
The first request is still running409 with code request_in_progress, or upload_in_use when you send the same upload_id; wait (Retry-After seconds when given) and send it again
The first request failed409 with code request_failed; it was refunded, so send it with a new key
After 24 hours or 5 re-runs, or a first request that never finished409 with code replay_expired; send it with a new key
A different file with the same key409
Default (keep_result omitted or true)
Response
The first request’s result, kept for 24 hours, with the same X-Request-ID and Idempotent-Replayed: true
keep_result=false on the first request
Response
Nothing is kept, so the file is detected again, free, up to 5 times within 24 hours
The first request is still running
Response
409 with code request_in_progress, or upload_in_use when you send the same upload_id; wait (Retry-After seconds when given) and send it again
The first request failed
Response
409 with code request_failed; it was refunded, so send it with a new key
After 24 hours or 5 re-runs, or a first request that never finished
Response
409 with code replay_expired; send it with a new key
A different file with the same key
Response
409

With a large-file upload, send the same upload_id again. If nothing was kept, Etchv needs the file again: that resend returns 409 upload_consumed, so upload the file again and send its new upload_id with the same key. A PDF over 32 pages is detected as a job whatever keep_result says: a resend returns that job, as for an async request.

Choose sync or async

ChoiceHow to request it
SynchronousUse the endpoint above; returns detection JSON directly
Background jobAppend /async; returns a 202 receipt. Collect the result
Completion eventAdd webhook_id to an async request. Webhooks
GPUAdd accelerator=gpu; Business/Enterprise, 3× credits when GPU runs. GPU guide
Files over 95 MBSend a large-file upload to the /async endpoint
Synchronous
How to request it
Use the endpoint above; returns detection JSON directly
Background job
How to request it
Append /async; returns a 202 receipt. Collect the result
Completion event
How to request it
Add webhook_id to an async request. Webhooks
GPU
How to request it
Add accelerator=gpu; Business/Enterprise, 3× credits when GPU runs. GPU guide
Files over 95 MB
How to request it
Send a large-file upload to the /async endpoint

Storage options are for embedding only. Large animations take longer because every frame is checked. A successful image detection still costs one CPU credit for the whole file. Image limits.

View source on GitHub

Your privacy, your choice

We use essential cookies to keep Etchv working. Optional analytics helps us improve the site. Analytics is on by default; you can turn it off in preferences. PostHog loads only if you accept all. Privacy policy

ETCHV

Privacy preferences

Choose what you allow on this browser. Analytics is enabled by default. You can turn it off, and change your choice at any time.

Essential

Always active

Supports secure sign-in, account sessions, site security, and remembering your privacy choice. These are needed for Etchv to work.

Analytics

Helps us understand visits and improve the website using page-view and device statistics, which do not use cookies. PostHog also measures visits and campaigns and may set cookies; it loads only after you save a choice with analytics on. Turning this off stops future analytics events.

We do not load advertising scripts. Meeting calendars load only when you open them. These preferences do not change your account, watermarking requests, or asset storage.

Your choice is remembered for 180 days on this browser. Privacy policy