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.
/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.
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.
| Field | Meaning |
|---|---|
watermarked | The same watermark was found in every frame, page or combined layer image |
watermark_id | Recovered 64-character hex ID, or null |
confidence | How certain the read was, from 0 to 1, taken from the least certain unit |
units | For each frame or page (unit): index, watermarked, confidence and watermark_id; indexes start at zero |
copy | 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 | 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 |
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,confidenceandwatermark_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) andopened_at(when they first opened the link, ornull)
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,metadataandcreated_at
{
"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:
copynames the recipient a traceable link made it for, andassetnames 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 iswatermarked: falsewith a nullwatermark_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.
| Situation | Response |
|---|---|
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 request | Nothing is kept, so the file is detected again, free, up to 5 times within 24 hours |
| The first request is still running | 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 | 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 | 409 with code replay_expired; send it with a new key |
| A different file with the same key | 409 |
- Default (
keep_resultomitted ortrue) - Response
- The first request’s result, kept for 24 hours, with the same
X-Request-IDandIdempotent-Replayed: true
keep_result=falseon 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
409withcoderequest_in_progress, orupload_in_usewhen you send the sameupload_id; wait (Retry-Afterseconds when given) and send it again
- The first request failed
- Response
409withcoderequest_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
409withcodereplay_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
| Choice | How to request it |
|---|---|
| Synchronous | Use the endpoint above; returns detection JSON directly |
| Background job | Append /async; returns a 202 receipt. Collect the result |
| Completion event | Add webhook_id to an async request. Webhooks |
| GPU | Add accelerator=gpu; Business/Enterprise, 3× credits when GPU runs. GPU guide |
| Files over 95 MB | Send 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 a202receipt. Collect the result
- Completion event
- How to request it
- Add
webhook_idto 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
/asyncendpoint
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.