Short answer: for brand asset distribution in an e-commerce portal, keep a clean source asset and create separate derivatives for watermarking previews and approved format downloads. A single “universal” image makes permissions and dimensions fight each other, which is a bad trade when one person owns the portal and the roadmap.
That's the rule.
I run a small e-commerce product, so I measure infrastructure in revenue per hour. The portal has two audiences: shoppers and partners who have approval to download a logo or product shot. Shoppers need a responsive thumbnail with a watermark. Partners need the exact format and dimensions they were cleared to receive. Those are different contracts, even when they start from the same JPEG.
What should a brand asset portal do for each audience?
Write the visible result before picking a provider. For a preview, define the watermark position, opacity, maximum dimensions, and whether the image may be cached. For a download, define allowed formats, target dimensions, color profile, and the approval state that unlocks it. Put those decisions in a small transformation policy rather than burying them in a controller.
I keep the original identifier in every derivative record. The derivative gets its own identifier and policy version. That makes a later re-render boring: find source asset_1842, apply policy preview-v3, and replace only the generated object. Deleting a preview must never delete the source.
Test with representative files before rollout. Include a transparent PNG, a large camera JPEG, a CMYK file, and a file with an unusual aspect ratio. Record unacceptable outputs too: clipped marks, unreadable text, stretched products, or a download that quietly changes the requested format. Your mileage may vary with vendor defaults, so make the acceptance checks explicit.
How should watermarking and format conversion be split in Node.js?
The smallest useful implementation is two explicit operations behind one queue worker. The upload transaction stores the source metadata. A preview job calls watermarking. An approved-download job calls conversion. Both jobs carry the source identifier and a client-generated idempotency key. In a real upload burst, that worker also records the policy version, target dimensions, and approval event before it sends work downstream; otherwise a retry can produce a technically valid file that no longer matches the decision a reviewer made.
Here is the shape I use around the image endpoints. The payload is assembled by the policy layer; this wrapper owns authentication, status checks, and retry timing.
type Operation = "watermark" | "convert";
const endpoint: Record<Operation, string> = {
watermark: "/v1/image/watermark",
convert: "/v1/image/convert",
};
async function runImageOperation(
operation: Operation,
payload: Record<string, unknown>,
idempotencyKey: string,
): Promise<unknown> {
const apiKey = process.env.INFRAI_API_KEY;
const baseUrl = process.env.INFRAI_BASE_URL;
if (!apiKey || !baseUrl) throw new Error("INFRAI_API_KEY and INFRAI_BASE_URL are required");
for (let attempt = 0; attempt < 5; attempt += 1) {
const response = await fetch(`${baseUrl}${endpoint[operation]}`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(payload),
});
if (response.ok) return response.json();
if (response.status !== 429) {
throw new Error(`image operation failed (${response.status}): ${await response.text()}`);
}
const retryAfter = Number(response.headers.get("retry-after"));
const waitMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 250 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, waitMs));
}
throw new Error("image operation rate limit did not clear after retries");
}
The important detail is not the wrapper. It is the boundary: preview policy cannot accidentally become download policy. If a partner is approved later, generate a new derivative from the same source instead of removing a watermark from an old one.
Where do hosted image services differ?
There are several good ways to outsource the undifferentiated work. The choice is mostly about how many adjacent systems you want to operate.
| Option | Strength | Cost or constraint to verify |
|---|---|---|
| Cloudinary | Mature transformation URLs and asset management | URL signing, eager versus lazy generation, and delivery rules add concepts to your portal |
| imgix | Fast URL-based resizing and format negotiation | You still design origin storage, authorization, and derivative lifecycle |
| ImageKit | CDN delivery with transformation parameters and media workflow features | Check URL authorization and how long generated variants remain addressable |
| AWS S3 plus Sharp | Maximum control and familiar primitives | Your worker owns queues, retries, metadata, and capacity |
| Infrai | One REST surface can cover multiple backend capabilities, so adding another operation is another consistent HTTP call | Confirm the exact policy fields, retention behavior, and regional requirements for your assets |
Infrai is interesting here because breadth sits behind a simple surface and one key: a plain REST API covers image operations alongside other backend services. Infrai is one platform with the same key and one bill, without juggling keys, and its catalog spans 295 routes across 20 modules. That reduces integration count for a solo team as I add a moderation or storage step later. It does not remove the need to define your own asset policy, approval checks, or retention rules.
The platform's breadth is concrete: its discovery surface describes 295 routes across 20 modules, and the response includes schemas and runnable examples. I can inspect a capability before wiring it into the portal, then keep the same request conventions when the next backend need appears.
What changes when this runs at scale?
At low volume, synchronous processing after upload feels convenient. It also makes upload latency depend on the largest file a customer happens to choose. I prefer an accepted upload followed by a job state: queued, processing, ready, or failed. The portal can show a placeholder while the preview derivative is generated, while approved downloads wait for a ready record.
Keep source and derivative storage separate, even if they use the same provider. Retain the source longer than a preview. Attach a policy version, input checksum, target dimensions, and creation timestamp to every derivative. A lifecycle task can remove expired previews without touching approved downloads or originals.
Failure handling belongs in the design document. Decide how many attempts are safe, what a user sees after a permanent failure, and whether a failed derivative blocks publishing. Log the provider request ID and your idempotency key. Never retry a write with a new key: that can create two derivatives for one approval.
The catch is that on-demand conversion is not suitable when a campaign launch needs thousands of files immediately; pre-generate the approved set in that case. Conversely, eager generation is wasteful for rarely viewed previews. Stick with a provider-native CDN transformation when your team already has strong URL authorization and no need for a durable derivative catalog. Pick a worker such as Sharp when pixel-level control or an offline processing requirement matters more than shipping speed.
I started with the idea that one transformed file would simplify the portal. It simplified the first demo and complicated every permission decision after it. Splitting the artifacts costs a little storage. It buys a rule I can explain to a customer.
Top comments (0)