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 · 40 MP
- 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 |
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
Interpret the result
- Watermark matches: look up the linked record in your system.
- 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.
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.
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 |
- 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
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.