---
name: ecommerce-background-replace-images
description: 'Replace or upgrade product photo backgrounds for ecommerce images. Use when the user asks to change a rough background into white background, premium studio, light lifestyle, seasonal, platform-ready, or consistent catalog backgrounds while preserving the original product with GPT Image 2.'
metadata:
  icon: "\U0001FA84"
  title: Ecommerce Background Replace Images
  companionSkill: gpt-image-2
  packageName: '@zjxuyunshi/ecommerce-background-replace-images'
  version: 0.0.1
---

# Ecommerce Background Replace Images

## When to Use

Use this skill when the user wants to keep the product but replace, clean, or upgrade the background. Typical requests include white background, transparent-feel background, premium studio background, catalog consistency, seasonal background, light lifestyle background, or removing messy source environments.

Use this when the product itself should remain essentially unchanged. Use `ecommerce-main-images` when the whole cover composition is being redesigned and `ecommerce-scene-images` when the request is a richer lifestyle scene.

## Inputs

- Required: product image. Preserve product shape, color, proportions, logos, packaging, labels, and distinctive details.
- Optional: desired background type: `white background`, `premium studio`, `light lifestyle`, `seasonal`, `category scene`, `brand color`, or `catalog unified`.
- Optional: reference images for background style, lighting, color palette, surface, and composition.
- Optional: platform, target ratio, output size, format, quality, and count.
- Optional: shadow/reflection preference. Default to natural soft shadow.

Do not alter the product unless the user explicitly asks for product retouching.

## Execution

Use `$gpt-image-2` image editing mode through `fusion-api.openai_image_edit_async_submit`. Upload the product image first, then optional background references.

Prompt structure:

```text
Create an ecommerce background replacement image.
Primary product: preserve image 1 accurately, including shape, color, proportions, material appearance, logos, labels, packaging, and distinctive details.
Background goal: <white background | premium studio | light lifestyle | seasonal | brand color | catalog unified>.
Reference usage: use images 2+ only for background style, lighting, surface, and color palette; do not copy unrelated products, text, logos, or watermarks.
Composition: product remains the hero, clean edges, realistic contact shadow/reflection, platform-ready crop, uncluttered background.
Avoid: product distortion, changed colors, removed logos, fake props implying included items, QR codes, phone numbers, platform badges, watermarks, unsupported claims.
```

Run:

```bash
oo connector run "fusion-api" --action "openai_image_edit_async_submit" --data @payload.json --json
```

Use exact `$gpt-image-2` payload fields.

## Result Handling

Read URLs from `.data.data[].url`. Download to `/Users/yunshi/Downloads/ecommerce-background-replace-images/<short-product-name>-<timestamp>/` with names like `background-replace-01.png`. Preview when practical and mention the selected background goal.

## Failure Handling

- Missing product image: ask for one.
- Ambiguous background request: default to premium studio, or ask if white-background compliance matters.
- Product changes too much: retry with stronger preservation wording.
- Too many references: choose the clearest background/style references.
- Connector handle, timeout, auth, billing, upload, or schema failure: follow `$gpt-image-2` guidance and report the exact blocker.