Batch image creation belongs in a durable job system, not inside one long request handler. Short answer: snapshot each product title and description, enqueue an idempotent item, save the generated asset under a stable key, and export a manifest containing every terminal result.
The useful boundary is the job contract. A Node.js API can accept the catalog and expose progress while Python workers reuse the same prompt and evaluation code that ran in a notebook. Don't make the language split the hard part. Make state, provenance, and review explicit before increasing concurrency.
How should a Node.js async job export results for an ecommerce catalog?
The request path should validate an upload, create a batch record, persist immutable item records, and return a job identifier. It should not wait for an image model. That keeps an ordinary web timeout from becoming the lifetime of a catalog run, and it gives operators a durable answer when they ask what happened to product SKU-1048.
Each item needs a stable product identifier, the exact title and description used, a prompt version, an input hash, generation settings, and a status. Copy the source fields into the batch rather than reading the live product row later. If a merchandiser changes a description halfway through processing, a retry must still represent the same logical input. The Node.js side only needs a narrow contract: create a batch, read batch status, and download the completed manifest. A queue message can carry the batch ID and item ID, while the database remains the source of truth. Keep model-specific request objects behind a worker adapter — they should not leak into queue payloads or exports. Use a small state machine such as pending, running, completed, retryable, and rejected. A review decision is separate from generation success, so reviewed or approved should not be treated as a synonym for completed. The worker claims one item, builds its versioned prompt, invokes an image adapter, stores the bytes, records their checksum and metadata, and then commits the terminal state. Order matters: marking an item complete before its bytes are durably stored creates a manifest that points nowhere, while storing first can leave an unreferenced object if the worker exits before the database update. A deterministic object key lets the next attempt reconcile that object instead of creating another logical result. Derive it from immutable fields such as product ID, prompt version, and input hash; row numbers are too easy to reorder.
Start with bounded concurrency and treat its value as configuration. A limit of four may be a sensible experiment setting, but it isn't a universal production number: account quotas, output dimensions, memory, model latency, and review capacity all change the useful ceiling. Increase worker count and per-worker concurrency separately, watching queue age and terminal-item throughput after each change.
Slow can be correct.
A focused worker and manifest example
The following Python example models the worker boundary even when a Node.js service owns ingestion and status endpoints. It has no invented public API route and no dependency on a particular image vendor. Production code supplies generate_image and store_bytes adapters, while tests can pass deterministic in-memory functions.
import asyncio
import hashlib
import json
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Awaitable, Callable, Literal
GenerateImage = Callable[[str, str], Awaitable[bytes]]
StoreBytes = Callable[[str, bytes], Awaitable[str]]
Status = Literal["completed", "retryable", "rejected"]
@dataclass(frozen=True)
class CatalogItem:
product_id: str
title: str
description: str
prompt_version: str
@dataclass(frozen=True)
class ManifestRow:
product_id: str
status: Status
input_hash: str
prompt_version: str
object_key: str = ""
checksum: str = ""
error_class: str = ""
def hash_input(item: CatalogItem) -> str:
source = "\0".join(
[item.product_id, item.prompt_version, item.title, item.description]
)
return hashlib.sha256(source.encode("utf-8")).hexdigest()
def build_prompt(item: CatalogItem) -> str:
return (
f"Catalog photograph of {item.title}. "
f"Product details: {item.description}. "
"Show one product on a neutral background. Do not add words or logos."
)
async def process_item(
item: CatalogItem,
limit: asyncio.Semaphore,
generate_image: GenerateImage,
store_bytes: StoreBytes,
) -> ManifestRow:
input_hash = hash_input(item)
object_key = f"catalog/{item.product_id}/{input_hash}.png"
try:
async with limit:
image = await generate_image(build_prompt(item), input_hash)
checksum = await store_bytes(object_key, image)
return ManifestRow(
product_id=item.product_id,
status="completed",
input_hash=input_hash,
prompt_version=item.prompt_version,
object_key=object_key,
checksum=checksum,
)
except (TimeoutError, ConnectionError) as exc:
return ManifestRow(
product_id=item.product_id,
status="retryable",
input_hash=input_hash,
prompt_version=item.prompt_version,
error_class=type(exc).__name__,
)
except ValueError as exc:
return ManifestRow(
product_id=item.product_id,
status="rejected",
input_hash=input_hash,
prompt_version=item.prompt_version,
error_class=type(exc).__name__,
)
async def run_shard(
items: list[CatalogItem],
generate_image: GenerateImage,
store_bytes: StoreBytes,
output: Path,
concurrency: int = 4,
) -> None:
limit = asyncio.Semaphore(concurrency)
rows = await asyncio.gather(
*(process_item(item, limit, generate_image, store_bytes) for item in items)
)
output.write_text(
json.dumps([asdict(row) for row in rows], indent=2),
encoding="utf-8",
)
This is intentionally a bounded-shard example. asyncio.gather retains the shard's results in memory, so a large catalog should be paged from durable storage and each state transition committed independently. Build the final export by querying terminal records rather than accumulating the entire run inside one worker process.
The manifest should include failures. An export of successes alone makes the catalog team compare source and output files to discover what vanished. In addition to the fields shown above, a production record can carry attempt count, creation and completion timestamps, media type, dimensions, byte size, model configuration, request correlation ID, and review status. Keep raw diagnostic detail in access-controlled logs; the export needs stable error classes and enough context for a safe retry.
Evaluation is the promotion gate
An image file is not automatically a usable catalog asset. A prompt can make attractive pictures while changing a product's color, inventing accessories, adding text, cropping an important edge, or ignoring a sparse description. A notebook demo with a few tidy products won't reveal how the prompt behaves across ambiguous titles, bundles, reflective surfaces, size variants, and the long tail of nearly empty records.
Freeze a representative evaluation cohort beside the prompt version. Score product fidelity, unwanted text, composition, background consistency, crop safety, and policy compliance. Automated checks can triage outputs, but human reviewers need to calibrate the rubric against actual merchandising decisions. I'm not sure which visual-evaluator threshold will match a particular catalog team's tolerance until reviewers label representative examples; that calibration data is what resolves the uncertainty.
Promote the prompt and settings together. Changing output dimensions, model configuration, or safety settings creates a new experiment even when the prompt text stays identical. Store the source fields, generated asset, rubric results, and reviewer decision under one experiment key so a notebook comparison can survive the move into a scheduled worker.
Cost tracking belongs in the same harness. Count requested, reused, generated, rejected, and accepted assets separately, because submitted calls are not the business result. Estimate cohort size before a run, set a batch budget, and stop expansion when the estimate is exceeded. Prompt variations multiply quickly — six variants across one cohort are six experiments, not one clever loop.
Small cohorts first.
Before copying this architecture, measure duplicate work after retry, time from enqueue to stored asset, terminal-state rate, evaluation pass rate by prompt version, and spend per accepted asset. Those measures reveal whether the pipeline can finish unattended and whether its output is worth publishing.
Failure handling without duplicate catalog assets
Retries should preserve logical identity. Transient transport failures can return an item to retryable with capped backoff and jitter; invalid source data should become rejected and wait for correction. Never turn a retry into a new item with a fresh object key. That hides duplicate spend and makes review history ambiguous.
The worker also needs a lease or equivalent claim mechanism so two processes don't intentionally own the same item. If a lease expires, the next worker should inspect the deterministic object location and recorded checksum before invoking generation again. This is why idempotency is an end-to-end property — a queue's delivery behavior alone cannot guarantee it.
Validate early: empty titles, duplicate product IDs, unsupported output settings, and disallowed source content should fail before generation. Keep the original input hash even for rejected rows. When the source is corrected, create a new logical item or batch version rather than overwriting evidence from the prior decision.
Observability should follow the state machine. Watch queue age, items in each state, retries per accepted image, storage bytes, and the gap between submitted and terminal items. A rising completion counter can look healthy while an older shard remains stuck; age by state exposes that failure mode. Correlation IDs connect the API request, queue claim, model call, storage write, and manifest row without putting sensitive descriptions into every log line.
Choosing the deployment boundary
There are three broad options: call a hosted image API, use managed inference inside an existing cloud environment, or operate model serving yourself. Compare them using the same frozen evaluation cohort. The relevant axes are output quality, data handling, retention, regional processing, quota behavior, latency, request metadata, capacity control, portability, and the operational skills already on the team.
| Deployment boundary | Suitable when | The catch |
|---|---|---|
| Hosted image API | The team wants to avoid model-serving operations | Confirm data handling, quotas, retention, and asset delivery before launch |
| Managed cloud inference | Identity and audit controls already live in that environment | The application still owns job state, evaluation, review, and export |
| Self-operated inference | Specialized models or infrastructure control justify ongoing ML operations | Not suitable when the team cannot own capacity, upgrades, and safety work |
Stick with a hosted boundary when operating inference would distract from catalog quality. Self-operation is appropriate only when its control is worth continuing responsibility for accelerators, upgrades, monitoring, and safety. A managed environment can align with an existing security model, but it does not remove the application's workflow responsibilities.
The same trade-off applies to a mixed Node.js and Python stack. Keep everything in Node.js when one runtime reduces operational burden and the evaluation tooling translates cleanly. Keep Python workers when notebook-to-production reuse materially reduces prompt drift. The catch is a second build and deployment path, so the shared contract must be small, versioned, and testable without either side importing the other's framework.
Sensitive free text deserves deliberate review. The HIPAA Security Rule, for example, defines administrative, physical, and technical safeguards for electronic protected health information. An ordinary ecommerce catalog is not automatically health data, but descriptions and uploads can contain unexpected information; security and legal teams should determine the applicable controls rather than assuming the catalog label settles the question.
Roll out with a representative shadow batch, review it, and then raise cohort size and concurrency independently. Preserve the previous asset pointer in the manifest so rollback selects known output without deleting provenance. The goal is a dull production workflow around a creative model: reproducible inputs, inspectable decisions, bounded work, and an export the catalog team can trust.
Top comments (0)