Quickstart

You need an image and an Etchv account with credits. The free trial includes 200 credits for seven days.

Set your API key

Create a key with watermarks:embed and watermarks:detect. Keep it on your server. For a local terminal:

export ETCHV_API_KEY="YOUR_API_KEY"

Embed a watermark synchronously

Replace photo.jpg with your image. Use a unique reference for this delivery.

Also send an idempotency key. This is a value you choose for one operation. If a network error makes you retry, send the same request with the same key, and Etchv will not run the work twice. Use a new key for each new operation. Retry safely.

curl --fail-with-body https://api.etchv.com/watermarks/images \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H "Idempotency-Key: campaign-01-partner-42" \
  -F 'file=@photo.jpg' \
  --form-string 'data={"delivery":"partner-42-preview"}' \
  -D response-headers.txt --output response-body

Check the status in response-headers.txt:

Save the watermark ID from X-Watermark-ID with your delivery record. Keep X-Request-ID to recover the request or to contact support. Save the returned bytes as they are. Re-encoding the file can affect recovery.

Detect the watermark

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

Compare watermark_id with the watermark ID you saved. The response also includes watermarked and confidence. If no watermark is found, watermark_id is null. Interpret detection results.

Build it into your application

Find your files again

Use X-Asset-ID and X-Source-Asset-ID to find the output and original in the asset library. Etchv keeps files for 30 days on the trial and up to a year on a paid plan. Records stay until you delete them.

Prefer an asynchronous request?

Add /async to the end of the embedding endpoint. Send the same fields. Then collect the result later, or ask for a webhook (a message Etchv sends to your server when the job finishes). Sync and async guide.