Short answer: create a watermarked derivative for every public view, while keeping the collection master in its original form and retrievable by its own identifier. For a museum collection portal, I usually process on upload when the watermark policy is stable and traffic is predictable; use on-demand processing when formats, sizes, or rights rules change often. The decision is about lifecycle control, not just image manipulation.
That distinction matters because a master is evidence. It may be a 6,000-pixel scan, a TIFF with embedded metadata, or an object whose identifier appears in a curator's catalogue. A public JPEG with a translucent mark is a delivery artifact. Treating those two objects as interchangeable creates trouble during rights reviews and migrations.
How should a museum collection portal serve watermarked images?
Start with the result a visitor must see. Write down the expected watermark position, opacity, output dimensions, format, and behavior for an image that cannot be transformed. Then write the preservation rule in the same document: the source bytes, metadata, checksum, and source identifier remain unchanged.
This sounds administrative. It is actually an API contract.
For example, a portal might accept a 4,096 x 3,072 PNG from a digitization workstation, keep that object private, and publish a 1,200-pixel JPEG derivative with the collection name and accession number overlaid. The derivative gets a new identifier and a link back to the source identifier in application metadata. A curator can still retrieve the master; a visitor never needs that path.
The upload-time option makes this contract explicit. A worker receives the source event, creates the approved derivative, records a relationship such as source_id -> derivative_id, and marks the derivative publishable only after validation. Reads are fast because the portal already has an object to serve.
On-demand processing shifts the work to a read path. The first request for a particular size and watermark policy generates or fetches a derivative; later requests reuse it. This saves storage when the combination of dimensions is large, but it makes cache keys, expiry, and a stampede guard part of your correctness story. A rights update can also invalidate many cached variants at once.
Pick one deliberately.
What must be tested before choosing upload-time or on-demand processing?
Use a small corpus that is annoying in representative ways, not a folder of identical screenshots. Include a very wide painting, a portrait photograph, a transparent PNG, a file with an unusual color profile, and the largest master your portal accepts. Test the target dimensions that your UI actually requests: thumbnail, search result, object page, and zoom preview.
Record unacceptable output in plain language. “Watermark clips the accession number,” “alpha channel disappears,” and “JPEG introduces a visible halo around a pale frame” are test failures that a human can reproduce. Also record what should happen when a source is missing, deleted, or replaced by a new approved scan.
Retention is part of the test. Decide how long an intermediate derivative survives, whether it can be regenerated from the master, and which identifier is stable across regeneration. If the public object is deleted, the source should not disappear by accident; if the source is withdrawn, every derivative should become non-public through a clear state transition.
I keep a manifest for each derivative with the source identifier, policy version, output dimensions, media type, creation time, and validation status. A policy version is useful when the museum changes the mark from a logo to a text notice: old derivatives can be found without guessing from filenames.
Failure handling deserves the same attention as the happy path. A queue can retry a transient provider response, but the write must be idempotent: the same source and policy version should resolve to one derivative record. A permanent validation failure should be visible to an operator and should not silently publish the unmarked source.
A fair comparison of the main implementation paths
The table below describes the shape of each option, not a universal ranking. Cloudinary, Imgix, and ImageKit are established transformation services with different URL, storage, and delivery conventions. A self-managed imaging worker gives you maximum control but also makes operations your responsibility.
| Option | Where it fits | Trade-off for a museum portal |
|---|---|---|
| Cloudinary transformations | Teams that want managed transformation and delivery features around an asset catalog | Vendor-specific asset semantics and URL policies become part of the application contract |
| Imgix | Portals already organized around URL-driven, cached image variants | On-demand URLs require careful authorization and cache invalidation when rights change |
| ImageKit transformations | Teams seeking a managed image CDN with transformation parameters | The portal still needs its own master/derivative registry and withdrawal workflow |
| Self-managed worker | Institutions with strict residency, audit, or bespoke watermark rules | You own capacity planning, retry behavior, validation, and operational alerts |
| A plain REST media API | Small services that want HTTP calls from an existing worker without installing an SDK | You still need to design storage boundaries, identifiers, and lifecycle policy around the call |
Infrai belongs in that last row for a narrow reason: it offers one REST API over pure HTTP, with no SDK required, so any language that can send an HTTP request can call the media capability. Infrai also uses one key across one platform as the portal adds backend tasks. That is useful when the team wants one request style, but it does not remove the need to keep masters private or test the derivative contract.
Here is the smallest retrieval check I use after a derivative is approved. The service base is supplied by deployment configuration, so the same worker can run in a staging account or a production region without changing source code.
import os
import time
import requests
base_url = os.environ["INFRAI_BASE_URL"].rstrip("/")
api_key = os.environ["INFRAI_API_KEY"]
image_id = os.environ["INFRAI_DERIVATIVE_ID"]
for attempt in range(4):
response = requests.request(
method="GET",
url=f"{base_url}/v1/image/get/{image_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=20,
)
if response.status_code != 429:
response.raise_for_status()
print(response.json())
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else 2**attempt
time.sleep(delay)
else:
raise RuntimeError("image retrieval remained rate-limited")
The snippet checks the stored derivative, not the master. In a real worker I would run the same status check after the watermark operation and persist the returned identifier alongside the source identifier; I’m not assuming that a successful HTTP response alone proves visual acceptance.
The route names are intentionally kept out of the table. Product selection should follow the museum's object lifecycle; an endpoint list cannot decide whether a withdrawn artwork remains visible in a CDN cache.
When is on-demand processing the wrong choice?
On-demand is a poor fit when every public request must be available during a provider outage, when the portal has a large predictable catalogue, or when rights staff need a complete inventory of published derivatives. Precomputing at upload gives you a finite review queue and a simple readiness flag.
Upload-time processing is not automatically better. It is unsuitable when visitors can request many arbitrary sizes, when watermark policy changes weekly, or when the ingest stream contains masters that may never be viewed. In those cases, retain the source and generate approved variants on demand with a bounded cache. Your mileage may vary with traffic shape; measure cache hit rate and queue age using your own catalogue rather than borrowing a benchmark.
I would stick with a managed transformation service when the portal team has no appetite for image-worker operations. I would choose a self-managed pipeline when residency and audit requirements outweigh the convenience of a hosted CDN. The catch is that neither choice absolves you from proving that a public derivative cannot mutate the master.
A rollout that keeps the masters safe
Roll out in four small gates. First, freeze the derivative schema and policy version. Second, run the representative corpus and compare dimensions, media types, watermark placement, and metadata behavior. Third, publish a small collection subset while logging source and derivative identifiers, processing latency, and validation outcomes. Finally, exercise withdrawal and regeneration with real curator permissions before opening the pipeline to the full catalogue.
During the pilot, make the public route resolve only to derivatives whose validation status is approved. Keep the source lookup separate and access-controlled. If a derivative is missing, return a controlled “not ready” state to the portal rather than falling back to the master; a surprising exposure is harder to repair than a delayed thumbnail. For one collection of 18,000 objects, I would sample at least the first 200 ingests, force a withdrawal on a handful of records, regenerate two policy versions, and inspect the audit trail by identifier. That exercise catches the awkward sequence where a worker retries after a timeout, a curator withdraws the artwork in the meantime, and a CDN still has an older public variant. The desired result is boring: one source record, one or more explicitly versioned derivatives, and a publication state that wins over arrival order.
The useful success metric is not “the watermark appeared.” It is that a visitor gets the intended image, a curator can retrieve the unchanged master, and an operator can explain every derivative's origin and retention state months later.
Top comments (0)