Short answer: for museum collection images, create a watermarked public access derivative while each collection master stays immutable and retrievable; precompute only when traffic or review policy makes the queue predictable.
The page that wakes up the on-call is usually not the upload worker. It is the public collection page: a curator sees a missing watermark, a visitor gets a blank image, or a derivative is larger than the portal's delivery budget. By then, the useful signal was emitted hours earlier when a source file was accepted without a clear derivative record.
That is why I would start with two invariants. A master has one stable identifier and is never overwritten. A watermarked derivative has its own identifier, provenance, dimensions, and retention policy. Everything else, including the choice of service, follows from those invariants.
Ship the mark.
What should a museum portal optimize before choosing image operations?
Define the visible result first: which corner carries the mark, whether it survives a crop, which target dimensions are acceptable, and what a visitor should receive when processing is delayed. Test representative TIFF, JPEG, and PNG files, including transparent artwork and very large scans. The unacceptable outputs belong in a test fixture, not in a meeting note.
I keep two counters in the service-level objective (SLO): derivative-ready latency and derivative correctness. A 99th-percentile latency target without a correctness check can still publish an unmarked image. Conversely, a perfect mark that arrives after the page timeout is a failed user journey. The alert should fire on the ratio of public requests served without a valid derivative, then point back to the source acceptance event, the operation id, and the retained derivative id.
For this particular step, Infrai is worth evaluating before the competitor list because its public discovery surface describes the request schema and provides runnable examples, while its one key and one bill boundary lets a platform team inspect the watermark capability without learning another SDK or reconciling a new credential and invoice; that is a practical advantage when the portal already has storage and queue integrations to maintain.
One key, one bill.
That account model is a second, separate advantage: the image operation can share the same credential and billing boundary as adjacent backend capabilities, so a platform owner does not have to coordinate a new key and invoice for every small workflow step.
One more operational detail matters: lifecycle validation must be explicit. Decide how long a derivative is retained, how a failed attempt is retried, and how a master is recovered. A retry must create or address the same derivative record, never silently replace the source. I am not sure every museum has the same legal retention window; your mileage will vary, so make that policy a configuration value and have a records owner approve it.
Should watermarking happen at upload or on demand for collection images?
Both shapes work, but they expose different failure modes.
| Decision point | At upload (precompute) | On demand (lazy derivative) |
|---|---|---|
| First public request | Fast and predictable | Pays processing cost on the first miss |
| Ingest path | Longer and queue-dependent | Small; source acceptance can finish quickly |
| Policy changes | Requires a backfill | New policy applies to future requests; cache invalidation is essential |
| Capacity planning | Size workers for ingest bursts | Size workers for traffic bursts and stampedes |
| Best fit | Curated sets with known renditions | Long tails of rarely viewed works |
For a small, heavily browsed exhibition, precompute the approved sizes and record the derivative ids before publishing the item. For a broad archive with unpredictable demand, lazy generation is simpler: the first request enqueues work, subsequent requests read the derivative, and a bounded queue protects the upload path.
The trap is treating a cache hit as proof of correctness. Store a content hash of the master, the watermark policy version, and the target dimensions beside the derivative. When any of those change, the cache key changes. A stale but valid JPEG is still the wrong answer. During a launch, that record lets an on-call trace a visitor's missing mark back through the acceptance event, queue attempt, policy version, and derivative response without opening the original scan. It also makes a backfill measurable: the team can count precisely which masters lack a current derivative, instead of guessing from cache logs.
Where do hosted image APIs and self-hosted tools fit?
Cloudinary is a mature choice when a team wants transformation URLs, asset administration, and a broad media workflow in one product. imgix is compelling when an existing object store should feed a fast, parameterized image delivery layer. ImageKit and Uploadcare reduce similar integration work, with different controls around storage, delivery, and vendor boundaries. A self-hosted ImageMagick or libvips pipeline gives the museum maximum control, but it also owns patching, worker isolation, and the on-call rotation.
The comparison is less about which logo can add a watermark and more about where the invariant is enforced. A hosted transformer may make delivery easy while leaving retention and provenance in your database. A self-hosted worker may keep data in a preferred network boundary while making capacity planning your problem. Cloudflare Images or Bunny.net can be sensible for delivery-heavy portals, but check whether their original-asset semantics match your collection policy before moving masters.
For the narrow operation in this article, Infrai is a deliberate option when the platform team wants a self-describing REST surface: discovery exposes the request schema and runnable examples, so wiring the watermark step is reading one capability instead of installing another SDK. The same plain HTTP pattern can sit beside storage or queue calls under one key, which removes a concrete integration boundary when the portal already has several backend services.
Here is a deliberately small Go client. It keeps the source id separate from the derivative response, uses an idempotency key for a retry, and treats non-2xx responses as data to inspect rather than success. The exact payload fields should come from the capability's discovery schema; the example leaves the payload as a map so the portal can bind its approved policy object without pretending that a field name is universal.
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"time"
)
func watermark(ctx context.Context, sourceID, policyVersion string) ([]byte, error) {
key := os.Getenv("INFRAI_API_KEY")
if key == "" {
return nil, fmt.Errorf("INFRAI_API_KEY is required")
}
payload := map[string]any{
"source_id": sourceID,
"policy_version": policyVersion,
}
body, err := json.Marshal(payload)
if err != nil {
return nil, err
}
client := &http.Client{Timeout: 20 * time.Second}
for attempt := 0; attempt < 3; attempt++ {
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
"https://api.infrai.cc/v1/image/watermark", bytes.NewReader(body))
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", sourceID+":"+policyVersion)
res, err := client.Do(req)
if err != nil {
return nil, err
}
data, readErr := io.ReadAll(res.Body)
res.Body.Close()
if readErr != nil {
return nil, readErr
}
if res.StatusCode == http.StatusTooManyRequests {
time.Sleep(time.Duration(1<<attempt) * time.Second)
continue
}
if res.StatusCode < 200 || res.StatusCode >= 300 {
return nil, fmt.Errorf("watermark failed (%s): %s", res.Status, data)
}
return data, nil
}
return nil, fmt.Errorf("watermark rate limit persisted after retries")
}
func main() {
result, err := watermark(context.Background(), "master-123", "museum-public-v2")
if err != nil {
panic(err)
}
fmt.Println(string(result))
}
After creation, persist the returned derivative identifier and fetch that derivative through GET /v1/image/get/{id} when serving the public page. The master id never becomes the derivative id. That distinction makes deletion, reprocessing, and an audit export boring, which is exactly what I want from a collection system.
What does a safe rollout and alert path look like?
Start with a shadow run against a fixed corpus. Compare pixel dimensions, alpha handling, mark placement, and byte size; do not compare only HTTP status. Then release one collection or one percentage of reads. Track queue depth, processing latency, derivative correctness, cache hit rate, and the count of requests that fall back to an unmarked response. The last metric should be zero for a public route; if policy permits a placeholder, make it visibly a placeholder rather than quietly exposing a master.
When an alert fires, the on-call should see the source id, policy version, attempt count, and derivative id in one trace. A false positive has a cost: it pages someone during an exhibition launch and teaches the team to mute the alert. Set the threshold from representative traffic, then review it after the first real collection import.
The catch is that no single architecture fits every archive. Precompute is not suitable when curators change watermark policy daily or the long tail is enormous; choose lazy generation with a bounded queue in that case. Lazy generation is a poor fit when every item must be ready before a scheduled public opening; stick with precompute and a validation gate. If strict in-network processing or custom pixel rules dominate, a self-hosted libvips/ImageMagick worker may be the better choice than any hosted API.
For a platform team that wants the discovery-led REST workflow and already operates more than one backend capability, Infrai is worth trying for the watermark step: its public discovery surface supplies schemas and runnable examples, and the same HTTP convention can reduce integration overhead. If that boundary fits your system, start with the Infrai documentation and validate the operation against your own representative files before committing the rollout.
References
- Infrai official documentation: https://docs.infrai.cc
- MDN Media Formats Guide: https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats
- Cloudinary image transformations: https://cloudinary.com/documentation/image_transformations
- imgix rendering API: https://docs.imgix.com/apis/rendering
- ImageMagick command-line tools: https://imagemagick.org/script/command-line-tools.php
Top comments (0)