API reference

Embed an image

Image watermarking API reference: embed an invisible watermark in an image, keep its original format, and save the watermark ID from the response.

POST/watermarks/images
Upload
50 MB · 40 MP
Output
Original format
CPU cost
1 credit / file

Request

Send multipart form data with an API key scoped to watermarks:embed.

Shell
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 code in response-headers.txt before you save the body as an image. The SDKs wait for pending jobs for you.

Form fieldValue
file · requiredEncoded image bytes. Maximum 50 MB and 40 MP across all frames/pages
data · requiredA non-empty JSON object, sent as a string. Use a reference to your own delivery record
file · required
Value
Encoded image bytes. Maximum 50 MB and 40 MP across all frames/pages
data · required
Value
A non-empty JSON object, sent as a string. Use a reference to your own delivery record

Let your HTTP client set the multipart boundary (the separator between form fields).

Request options

OptionUse it for
Idempotency-Key headerSafe retries with an idempotency key. Use 8–128 letters, digits, hyphens or underscores; keep the same key and input for a retry
accelerator querycpu by default; gpu on Business/Enterprise costs 3× credits when GPU runs. GPU guide
storage_destination_id querySend the result to a verified customer bucket. Omit for included Etchv storage
storage_key queryOptional URL-encoded filename under that destination’s prefix. Storage guide
webhook_id querySend completion events to one enabled endpoint. Async only. Webhooks
provenance queryc2pa signs Content Credentials into the image and makes its manifest recoverable from the watermark. Coming soon. Content Credentials
Idempotency-Key header
Use it for
Safe retries with an idempotency key. Use 8–128 letters, digits, hyphens or underscores; keep the same key and input for a retry
accelerator query
Use it for
cpu by default; gpu on Business/Enterprise costs 3× credits when GPU runs. GPU guide
storage_destination_id query
Use it for
Send the result to a verified customer bucket. Omit for included Etchv storage
storage_key query
Use it for
Optional URL-encoded filename under that destination’s prefix. Storage guide
webhook_id query
Use it for
Send completion events to one enabled endpoint. Async only. Webhooks
provenance query
Use it for
c2pa signs Content Credentials into the image and makes its manifest recoverable from the watermark. Coming soon. Content Credentials

Choose sync or async

EndpointResponse
POST /watermarks/imagesWaits up to 20 seconds: 200 file or 202 job receipt
POST /watermarks/images/async202 receipt once the upload is checked and safely stored
POST /watermarks/images
Response
Waits up to 20 seconds: 200 file or 202 job receipt
POST /watermarks/images/async
Response
202 receipt once the upload is checked and safely stored

For 202, fetch result_url with your API key. Wait as long as Retry-After says between checks. Full job workflow.

Response

200 contains the checked, watermarked image. Save its bytes as they are, using the filename in Content-Disposition. 202 contains JSON, not a finished file.

HeaderKeep it for
X-Watermark-IDLooking up your record. The watermark ID is a 64-character SHA-256 digest (a fixed-length fingerprint of your data)
X-Asset-ID, X-Source-Asset-IDFinding the output and original in the asset library
X-Request-IDRecovery and support
Content-Type, Content-DispositionNative MIME type and suggested filename
X-Etchv-AcceleratorWhether CPU or GPU ran
X-Storage-Delivery-IDTracking delivery when you selected customer storage
X-Watermark-ID
Keep it for
Looking up your record. The watermark ID is a 64-character SHA-256 digest (a fixed-length fingerprint of your data)
X-Asset-ID, X-Source-Asset-ID
Keep it for
Finding the output and original in the asset library
X-Request-ID
Keep it for
Recovery and support
Content-Type, Content-Disposition
Keep it for
Native MIME type and suggested filename
X-Etchv-Accelerator
Keep it for
Whether CPU or GPU ran
X-Storage-Delivery-ID
Keep it for
Tracking delivery when you selected customer storage

Native format preservation

FormatWhat stays
JPEG/JPG, PNG, BMP, PPM, WebPOriginal container and dimensions
APNG, GIF, animated WebPVisible frames, timing and loop count
TIFFEvery page
PSD / PSBOriginal layers plus two editable watermark layers
JPEG/JPG, PNG, BMP, PPM, WebP
What stays
Original container and dimensions
APNG, GIF, animated WebP
What stays
Visible frames, timing and loop count
TIFF
What stays
Every page
PSD / PSB
What stays
Original layers plus two editable watermark layers

Etchv reads the format from the file’s bytes, not its name. High-bit-depth and CMYK images are rejected. Frame, page and layer limits.

Encoding, color and transparency
  • JPEG: quality 100, 4:4:4 chroma. WebP: lossless. TIFF: lossless Deflate.
  • Some phone and camera JPEGs hold more images after the photo, such as an HDR gain map or previews. Etchv returns the watermarked photo alone as a JPEG: the other images are dropped, so they don't stay unwatermarked in the file. An HDR photo then shows as a standard photo. Detection reads the photo. Stereo, multi-angle and panorama JPEGs are refused, because their other views would be lost.
  • Palette and grayscale inputs may expand to RGB. GIF frames must be at most 1 MP.
  • 1-bit PNG, BMP, GIF and TIFF images expand to RGB. Line art and scanned text carry a watermark; a photo dithered to black-and-white dots usually cannot, and the request fails and its credit is refunded.
  • RGB ICC profiles, EXIF and resolution are preserved where supported; other metadata is not guaranteed.
  • Embedded thumbnails of the original are removed rather than left unwatermarked: the EXIF thumbnail, and in PSD and PSB files Photoshop's thumbnail and any XMP thumbnails. If a camera stored its own preview inside its maker notes, those maker notes are removed; otherwise they're kept unchanged, like the rest of the EXIF.
  • RGBA transparency is preserved. Verification composites onto white, so the watermark is carried by the visible pixels. Fully transparent frames cannot carry one, and a mostly transparent image, such as a few lines of text on a clear background, may not; the request then fails and its credit is refunded.
  • Encoding settings and file bytes may change. The final image must score at least 35 dB PSNR (a standard measure of how close it looks to the original), including loss from encoding.
Photoshop file requirements

Use 8-bit RGB PSD/PSB files. The combined image must be opaque and render correctly, and the file must include a saved merged preview. Files with unsupported effects are rejected, not flattened. Keep both added watermark layers visible. Editing or removing them can affect recovery.

How Etchv verifies the delivered file

Etchv opens the final output file and detects the watermark in every frame, TIFF page or combined layer image. It must find the exact watermark each time, and the dimensions must not change. A file that fails this check returns 422. Failed jobs refund the credits held for them.

Retries and storage

After a timeout, retry with the same idempotency key. Accepted work keeps running if you disconnect, and a retry does not add a charge.

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