API reference
Video watermarking
Video watermarking API reference: add an invisible watermark to every frame of H.264 MP4 and MOV files while keeping supported audio. Up to 20 MB.
/watermarks/videos- Upload
- 20 MB · H.264
- Marking
- Every frame
- CPU cost
- 1 credit / 24 frames*
For embedding, 1 credit for each started block of 24 frames. Detection costs 1 credit per file.
Request
Send a supported MP4 or MOV file and a JSON reference object that is not empty. Your
API key needs the watermarks:embed permission.
curl --fail-with-body https://api.etchv.com/watermarks/videos/async \
-H "X-API-Key: $ETCHV_API_KEY" \
-H "Idempotency-Key: campaign-preview-42" \
-F 'file=@preview.mp4' \
--form-string 'data={"delivery":"campaign-preview-42"}'This returns a 202 receipt. Collect the result
with a key from the same Organization. The finished file keeps its container,
frame timing and supported audio. The audio is not watermarked.
Choose sync or async
| Operation | Endpoint |
|---|---|
| Embed | POST |
| Detect | POST with file and watermarks:detect |
| Background embed / detect | Append /async to either endpoint |
- Embed
- Endpoint
POST/watermarks /videos
- Detect
- Endpoint
POSTwith/watermarks /videos /detect fileandwatermarks:detect
- Background embed / detect
- Endpoint
- Append
/asyncto either endpoint
A sync request waits briefly and returns 202 if the work is still running. Both
operations run as durable jobs, which keep going even if your connection drops.
Optional query parameters: accelerator=gpu on Business and Enterprise plans,
webhook_id for async requests, and storage_destination_id and storage_key for
embedding.
All options.
Supported files
All limits apply at once. For example, the 240-frame cap allows 10 seconds at 24 fps.
| Requirement | Limit |
|---|---|
| Container / codec | MP4 or MOV; one progressive 8-bit H.264 track, YUV 4:2:0 |
| Timing | Constant 1–60 fps, starts at zero; no rotation |
| Duration / frames | 120 seconds / 240 frames |
| Dimensions | Even dimensions, square pixels; 1 MP per frame, 40 MP total |
| Upload / output / detection | 20 MB / 100 MB / 95 MB |
| Audio | None, or one synchronized mono/stereo AAC-LC track |
- Container / codec
- Limit
- MP4 or MOV; one progressive 8-bit H.264 track, YUV 4:2:0
- Timing
- Limit
- Constant 1–60 fps, starts at zero; no rotation
- Duration / frames
- Limit
- 120 seconds / 240 frames
- Dimensions
- Limit
- Even dimensions, square pixels; 1 MP per frame, 40 MP total
- Upload / output / detection
- Limit
- 20 MB / 100 MB / 95 MB
- Audio
- Limit
- None, or one synchronized mono/stereo AAC-LC track
HDR, variable frame rates, fragmented MP4, other codecs, extra tracks, subtitles and attachments are not supported. Video must use a constant frame rate.
What verification checks
Etchv must detect the exact watermark in every frame of the final encoded video. Each frame must also meet 35 dB PSNR, a measure of how close it looks to the original, after allowing for color conversion. Audio packets and timing are copied and checked. Metadata in the MP4/MOV wrapper is copied where supported, but not byte-for-byte. Editing, transcoding or recompression can affect recovery.
Durable embedding and detection
- Embed result: native video bytes at
/watermarks./jobs /{request_id} /result - Detect result: JSON at
/watermarks./detection-jobs /{request_id} /result - Per-frame results:
units, numbered from zero. The top-level watermark ID is present only when Etchv finds the same watermark in every frame. - Retry: send the same upload and
Idempotency-Key. A dropped connection does not cancel the work.
Follow Retry-After when polling. A video job’s deadline is 30 minutes plus 15
seconds per frame, up to 90 minutes; completed results last 24 hours. Retry and recovery details.
Credits
| Operation | CPU credits |
|---|---|
| Embed | 1 per started 24 frames: 24 frames cost 1, 25 cost 2, 120 cost 5, 240 cost 10 |
| Detect | 1 per file, whatever its length |
- Embed
- CPU credits
- 1 per started 24 frames: 24 frames cost 1, 25 cost 2, 120 cost 5, 240 cost 10
- Detect
- CPU credits
- 1 per file, whatever its length
Embedding and detection are charged separately. Credits are reserved when Etchv accepts the request, charged once on success and refunded on failure. Retries and downloads of saved results cost no extra credits. GPU pricing.
Python: embed_video / detect_video. Node.js: embedVideo / detectVideo.
The result’s image field contains the video bytes. Save it with the returned
filename and content type. The SDKs check for the result until their configured
timeout.
Asset library
X-Asset-ID identifies the output. X-Source-Asset-ID identifies the original.
File retention · Customer storage.