| name | ecommerce-image-workflow |
| description | Use when designing, implementing, or improving ecommerce AI image-generation workflows for product main images, lifestyle scenes, detail-page images, campaign posters, batch variants, task queues, review flows, exports, or generation-state UX. Especially relevant for this project using gpt-image-2, Next.js 16, and FastAPI. |
Ecommerce Image Workflow
Use this skill for productized ecommerce image-generation flows, not generic image prompts.
Core Principles
- Treat image generation as a task workflow: inputs, validation, prompt build, model call, result storage, review, retry, export.
- Keep product truth intact: do not change the product's core appearance, structure, color, quantity, included accessories, or claims.
- Separate user intent from model prompt: collect structured ecommerce fields first, then render a controlled prompt on the backend.
- Prefer async jobs:
gpt-image-2 can be slow, so use task states, progress UI, retry, and clear failure messages.
- Save reproducibility data: final prompt, template version, model, params, request id, input assets, output assets.
Workflow Types
Choose the workflow before designing UI or backend APIs:
- Main image: clean commercial product image, strong subject, platform-safe composition.
- Lifestyle scene: product in realistic use context, target audience and scene-driven.
- Detail-page set: multiple images telling a product story: feature, material, size, usage, package.
- Campaign creative: promotion, holiday, launch, social or ad image with stronger visual concept.
- Batch variants: same product, multiple backgrounds/styles/copy angles for A/B testing.
Required Task Inputs
For every generation task, collect or infer:
- Product: name, category, description, selling points, target audience, price tier.
- Assets: source product image, optional brand assets, optional reference images.
- Output: image type, platform, aspect ratio, size, quality, format.
- Creative direction: scene, background, style, lighting, composition, mood.
- Constraints: forbidden changes, compliance notes, required/forbidden text.
Backend Flow
Implement generation as a backend-owned pipeline:
- Validate product, assets, and generation params.
- Render prompt from a versioned template.
- Create a task with status
queued.
- Worker sets status
running and calls gpt-image-2.
- Decode
b64_json, store original output and thumbnail.
- Persist metadata: model params, prompt, request id, duration, errors.
- Set status
succeeded or failed.
- Frontend polls or subscribes to updates.
Status Model
Use these states unless the project already defines another model:
created -> queued -> running -> succeeded
created -> queued -> running -> failed
created -> queued -> cancelled
Show user-facing explanations for failed, not raw provider dumps.
Frontend Flow
Design UI around confidence and control:
- Step 1: choose product or upload product asset.
- Step 2: choose image type and target platform.
- Step 3: configure scene/style/ratio/quality.
- Step 4: preview generated prompt summary, not necessarily full prompt.
- Step 5: submit task and show progress.
- Step 6: review results, favorite, retry, create variants, export.
Batch Generation
For variants, expand one user request into deterministic child jobs:
- vary one or two dimensions at a time: background, style, composition, copy angle, ratio.
- show estimated count and cost before submission.
- preserve parent task id and variant dimensions in metadata.
- allow per-image retry instead of rerunning the whole batch.
Done Criteria
A workflow is complete when:
- The user can understand what will be generated before spending credits.
- The backend can reproduce how an output was created.
- Failed tasks can be diagnosed and retried safely.
- Generated assets can be reviewed, compared, and exported.
