Image Watermarking

Overview

This page covers image-specific features of the DeepMark watermarking API: quality settings that control the robustness/visibility tradeoff, spatial tiling, visual comparisons, and supported image formats.

For general API usage (authentication, submitting jobs, downloading results), see the API Key Guide.

Quality Settings

Quality settings control the tradeoff between watermark robustness (how well the watermark survives compression, cropping, screenshots) and visual quality (how invisible the watermark is).

Without run_parameters, every setting uses the default for the image's resolution tier (tables below). If you send run_parameters, include all five keys to choose every setting explicitly: a key you leave out does not keep its tier default but takes a fixed value (quality_modefast, embed_strength4, dark_suppression0.0, dark_threshold40, flat_area_retention0.4). To change one setting, copy the others from the Defaults Summary column for your tier.

How to pass quality settings

Send quality settings in the run_parameters field of POST /client/embed, as one JSON object with any of the keys below. Only models with modifiable_run_parameters: true in /client/models accept them. Settings sent as separate form fields are ignored.

Example Request (with quality settings)

Set MODEL_ID to an image model whose modifiable_run_parameters is true, and send exactly min_watermark_length bits as the watermark (64 for the model in this example):

curl -sS -X POST "https://app.deepmark.me/client/embed" \
  -H "X-Client-Api-Key: $DEEPMARK_API_KEY" \
  -F "file=@input.jpg;type=image/jpeg" \
  -F "watermark=1100110011001100110011001100110011001100110011001100110011001100" \
  -F "model=$MODEL_ID" \
  -F 'run_parameters={"quality_mode": "precise", "embed_strength": 4, "dark_suppression": 0.8, "dark_threshold": 80, "flat_area_retention": 0.5}' \
  | tee embed.json
echo

EMBED_JOB_ID=$(grep -o '"job_id": *"[^"]*"' embed.json | cut -d'"' -f4)

Then wait for the watermarked file with the wait_for_result function from step 3 of the API Key Guide quickstart, defined in the same terminal:

wait_for_result "$EMBED_JOB_ID" watermarked.jpg

To check the watermark, send watermarked.jpg to POST /client/detect with the same model, as in steps 4 and 5 of the quickstart.

Each parameter has different defaults depending on which resolution tier the input image falls into:

Parameters

1. quality_mode

Chooses the resolution used for perceptual masking. precise computes the mask at the image's full resolution for finer control; fast uses a lower-resolution mask to reduce processing time. Without overrides, images up to 720 pixels high use precise and taller images use fast. When sending any overrides, include this key to keep the mode for your tier; omitting it uses fast.

2. embed_strength

Controls how strongly the watermark signal is blended into the image. This is the primary knob for the robustness vs. visibility tradeoff.

Range: whole numbers from 1 to 7. Default: 4 for all resolutions.

3. dark_suppression

Controls how much the watermark is reduced in dark regions of the image. Dark areas have less perceptual headroom to hide the watermark, so without suppression, artifacts become visible as noise or banding in shadows.

Defaults by resolution tier

1. ≤480p — 0.0
2. 480–720p — 0.4
3. 720–1080p — 0.6
4. >1080p — 0.95

Higher resolutions use stronger protection because dark-region artifacts are more noticeable on large displays.

4. dark_threshold

Controls the luminance threshold below which a region is treated as dark for the purposes of dark_suppression. Higher values mean more of the image is considered dark and receives suppression.

This parameter works together with dark_suppression — it defines where protection applies, while dark_suppression defines how much.

Defaults by resolution tier

1. ≤480p — 0
2. 480–720p — 40
3. 720–1080p — 60
4. >1080p — 127

5. flat_area_retention

Controls the minimum watermark strength retained in smooth, flat areas — regions with low texture like sky, walls, gradients, and solid backgrounds. These areas have very little visual complexity to mask the watermark, making artifacts more noticeable.

Defaults by resolution tier

1. ≤480p — 0.7
2. 480–720p — 0.6
3. 720–1080p — 0.4
4. >1080p — 0.3

Lower resolutions use higher retention because fewer pixels means less room for the watermark to hide.

Defaults Summary

Tiling

For large images, the watermark is embedded using spatial tiling — the image is divided into a grid and each tile is watermarked independently. This improves robustness against cropping (each tile carries the full watermark) and ensures consistent quality regardless of resolution.

Tiling is handled automatically — no client configuration is needed.

Visual Comparison

The following examples demonstrate watermark quality across different resolutions. Each comparison shows a passthrough re-encode (same decode→JPEG encode pipeline, no watermark) alongside the watermarked output, so any visual difference is purely from the watermark — not from codec re-compression.

Original vs. Optimally Watermarked

Drag the slider to compare the original image with its watermarked version. The watermark is designed to be imperceptible to the human eye while remaining detectable by the system.

~1920px (Full HD)

Passthrough (no watermark)

Watermarked (optimal)

<>

Loading images…

Detection: confidence ~97%, accuracy 100%, BCH OK. Tiles: 4×4.

~5000px (5K+)

Passthrough (no watermark)

Watermarked (optimal)

<>

Loading images…

Detection: confidence ~94%, accuracy 100%, BCH OK. Tiles: 8×8.

~8000px (8K)

Passthrough (no watermark)

Watermarked (optimal)

<>

Loading images…

Detection: confidence ~98%, accuracy 100%, BCH OK. Tiles: 8×8.

With resolution-adaptive defaults, the watermark is visually imperceptible. Dark regions are protected from noise artifacts, flat areas like sky and gradients retain smooth appearance, and the watermark signal is concentrated in textured regions where the human eye is least sensitive.

Watermark Delta Visualization

The images below show |watermarked − passthrough| amplified 30× and rendered as white on black. Both images went through the same JPEG encode pipeline, so the difference is purely from the watermark. Brighter pixels indicate stronger watermark energy.

~1920px

100%

~5000px

100%

~8000px

100%

The watermark signal is distributed uniformly across the image. The consistent pattern demonstrates that the perceptual masking adapts to image content — watermark energy is suppressed in dark and flat regions and concentrated in textured areas where it is least visible.

Image Format Support

Supported Formats

1. JPEG (.jpg, .jpeg)
2. PNG (.png)
3. WebP (.webp)

Supported Resolutions

From 256×256 up to 16K (16384×16384) pixels. Images outside this range may be rejected or automatically resized.

Watermark Length

Each model takes a watermark of one fixed length: send exactly min_watermark_length bits, as listed by GET /client/models. The API rejects any other length. The 64-bit TurboMark models protect the payload with error correction: it is combined with an 8-bit organisation ID and a 7-bit checksum and encoded into the model's 256-bit watermark. Detection combines the readings from all tiles, then decodes and checks the payload.

Output Format

The watermarked image is returned in the same format as the input. JPEG quality is preserved at the source level to minimize re-compression artifacts.