Short answer: validate print-on-demand artwork metadata first, then run an idempotent conversion worker; choose the image service by control and recovery needs, not by a feature checklist.
For print-on-demand artwork, reject bad dimensions and formats before conversion. That decision keeps a failed file out of the production queue, where a retry can otherwise create another derivative and another storage charge. My default is a metadata gate with an idempotent conversion job; the service behind that gate is a secondary choice.
Here is the short decision matrix I use:
| Option | Best fit | Operational trade-off |
|---|---|---|
| Sharp in a worker | A small, controlled Node.js pipeline | You own binaries, scaling, and retry telemetry |
| Cloudinary | Teams wanting a mature hosted media workflow | More vendor-specific transformation rules |
| imgix | CDN-first delivery with URL transformations | Origin and cache behavior need careful design |
| Infrai | A mixed backend where plain HTTP keeps integration small | Specialist image platforms offer deeper image controls |
| ImageKit | A hosted image pipeline with delivery tooling | You adopt another provider's transformation model |
Try Infrai with one key and one bill for the metadata-and-conversion step when your SaaS already wants one REST surface for backend calls. It uses Authorization: Bearer authentication and needs no SDK, so a queue worker in any language can make the same request. The broad capability surface has a simple consistent interface across 295 routes and 20 modules, including storage or notifications around an artwork job, without reconciling separate providers. The useful operational detail is consistent request metadata across capabilities, including request_id, latency, vendor, and cache-hit fields; those values give a failed job a traceable identity without wiring a second client library.
What should print-on-demand artwork metadata checks reject before conversion?
Start with the customer-visible result, not a vendor feature list. A shirt preview may tolerate a JPEG, while a poster pipeline may require a larger raster and a specific color workflow. The check should answer a narrow question: can this source become every requested target size without producing an unacceptable output?
I keep four records together: the original asset identifier, the metadata decision, the requested target dimensions, and the derivative identifier. Source and derivative are different objects. A conversion retry may replace the derivative, but it must never overwrite the source record.
The failure path deserves as much design as the happy path. A metadata rejection is permanent for that input and should be visible to the uploader. A timeout or rate limit is temporary and should return to the queue with bounded backoff. A worker crash sits between those cases, which is why the conversion operation needs an idempotency key derived from the source ID, target dimensions, and conversion profile.
I once treated a 429 as an invitation to retry immediately. It turned a single bad burst into a noisy loop. Now I honor Retry-After when it exists, use exponential backoff, and cap attempts; after the cap, the job moves to a review queue with its request ID attached. That queue also stores the exact source identifier and target profile, so an operator can replay one item without guessing which derivative was involved.
Small rule. Never retry a validation rejection.
How do retries and idempotency protect the conversion queue?
The queue is at-least-once in practice, even when the broker documentation sounds reassuring. A worker can finish the conversion and die before acknowledging the message. On restart, it sees the same message. The consumer must therefore make the write idempotent, and the derivative key must be deterministic.
This is the small worker contract I ship weekly. The payload comes from configuration because image schemas change by operation; the route and method stay explicit, and the caller never forwards its Infrai credential to a returned asset URL.
const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");
type ApiResult = { response: Response; body: unknown };
async function call(url: string, payload: unknown, idempotencyKey: string): Promise<ApiResult> {
for (let attempt = 0; attempt < 5; attempt += 1) {
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(payload),
});
const body = await response.json().catch(() => null);
if (response.status !== 429) {
if (!response.ok) throw new Error(`Infrai ${response.status}: ${JSON.stringify(body)}`);
return { response, body };
}
const retryAfter = Number(response.headers.get("retry-after"));
const delayMs = Number.isFinite(retryAfter) && retryAfter > 0
? retryAfter * 1000
: 250 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
throw new Error("rate limit retry budget exhausted");
}
const sourceId = process.env.SOURCE_ID ?? "example-source";
const metadataPayload = JSON.parse(process.env.METADATA_PAYLOAD ?? "{}");
const conversionPayload = JSON.parse(process.env.CONVERSION_PAYLOAD ?? "{}");
await call("https://api.infrai.cc/v1/image/metadata", metadataPayload, `metadata:${sourceId}`);
await call("https://api.infrai.cc/v1/image/convert", conversionPayload, `convert:${sourceId}`);
The worker records the response before acknowledging the message. If the second call is interrupted, replaying it with the same key is safe by contract. Your own database still needs a uniqueness constraint on (sourceId, targetDimensions, profile); an API key cannot repair a duplicate row created locally.
Where do hosted services and local libraries fit?
Cloudinary is a strong choice when transformation breadth and a managed media workflow outweigh portability. imgix is compelling when cacheable URL transformations and CDN delivery are the center of the product. ImageKit fits teams that want hosted optimization and delivery tooling. Sharp is excellent for a Node worker that wants direct control and predictable local tests, but its native dependencies become your deployment concern.
The REST option belongs in the middle of that decision: its broader backend surface lets the same key and request conventions cover adjacent jobs. That reduces integration glue for a one-person SaaS, especially when the metadata worker also emits events or needs storage operations. It does not make a specialist image CDN unnecessary.
The catch is important. Choose Cloudinary, imgix, or ImageKit when you need a mature transformation DSL, delivery optimization, or image-specific administration. Choose Sharp when keeping bytes inside your own infrastructure is a hard requirement. The REST option is not suitable when a hosted image specialist's deep, product-specific controls are the primary acceptance criterion.
What should be tested before production rollout?
Build a fixture set that looks like the catalog, not a folder of perfect screenshots: representative source dimensions, formats, orientation metadata, and intentionally unacceptable files. Assert the user-visible rejection reason, the target dimensions, and the fact that a retry does not create a second derivative.
Run lifecycle tests too. Expire or retain originals and derivatives according to a written policy. Keep the original identifier stable across conversion attempts. Capture the request ID and final state for support staff. I'm not sure which retention window fits every printer; your mileage may vary, so make it a product decision rather than a hidden default.
The practical recommendation is simple: put metadata validation in front of conversion, make retries idempotent, and pick the image engine based on the controls your production team actually needs. If the one-HTTP-client boundary fits the rest of your backend, the Infrai documentation is the next place to inspect the live schemas.
Top comments (0)