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 |
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
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.
- Palette and grayscale inputs may expand to RGB. GIF frames must be at most 1 MP.
- RGB ICC profiles, EXIF and resolution are preserved where supported; other metadata is not guaranteed.
- RGBA transparency is preserved. Verification composites onto white; fully transparent frames cannot carry a watermark.
- 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.