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.
/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.
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-bodyCheck the status code in response-headers.txt before you save the body as an image.
The SDKs wait for pending jobs for you.
| Form field | Value |
|---|---|
file · required | Encoded image bytes. Maximum 50 MB and 40 MP across all frames/pages |
data · required | A 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
| Option | Use it for |
|---|---|
Idempotency-Key header | 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 | cpu by default; gpu on Business/Enterprise costs 3× credits when GPU runs. GPU guide |
storage_destination_id query | Send the result to a verified customer bucket. Omit for included Etchv storage |
storage_key query | Optional URL-encoded filename under that destination’s prefix. Storage guide |
webhook_id query | Send completion events to one enabled endpoint. Async only. Webhooks |
provenance query | c2pa signs Content Credentials into the image and makes its manifest recoverable from the watermark. Coming soon. Content Credentials |
Idempotency-Keyheader- 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
acceleratorquery- Use it for
cpuby default;gpuon Business/Enterprise costs 3× credits when GPU runs. GPU guide
storage_destination_idquery- Use it for
- Send the result to a verified customer bucket. Omit for included Etchv storage
storage_keyquery- Use it for
- Optional URL-encoded filename under that destination’s prefix. Storage guide
webhook_idquery- Use it for
- Send completion events to one enabled endpoint. Async only. Webhooks
provenancequery- Use it for
c2pasigns Content Credentials into the image and makes its manifest recoverable from the watermark. Coming soon. Content Credentials
Choose sync or async
| Endpoint | Response |
|---|---|
POST | Waits up to 20 seconds: 200 file or 202 job receipt |
POST | 202 receipt once the upload is checked and safely stored |
POST/watermarks /images - Response
- Waits up to 20 seconds:
200file or202job receipt
POST/watermarks /images /async - Response
202receipt 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.
| Header | Keep it for |
|---|---|
X-Watermark-ID | 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 | Finding the output and original in the asset library |
X-Request-ID | Recovery and support |
Content-Type, Content-Disposition | Native MIME type and suggested filename |
X-Etchv-Accelerator | Whether CPU or GPU ran |
X-Storage-Delivery-ID | Tracking 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
| Format | What stays |
|---|---|
| JPEG/JPG, PNG, BMP, PPM, WebP | Original container and dimensions |
| APNG, GIF, animated WebP | Visible frames, timing and loop count |
| TIFF | Every page |
| PSD / PSB | Original 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.