---
name: ecommerce-product-replace-images
description: 'Replace a product in a reference scene with the user''s product photo for ecommerce visuals. Use when the user asks to put their product into an existing scene, replace competitor products, swap products in lifestyle images, or create marketplace-ready product replacement composites with GPT Image 2.'
metadata:
  icon: "\U0001F501"
  title: Ecommerce Product Replace Images
  companionSkill: gpt-image-2
  packageName: '@zjxuyunshi/ecommerce-product-replace-images'
  version: 0.0.1
---

# Ecommerce Product Replace Images

## When to Use

Use this skill when the user wants to replace a product in a reference image or scene with their own product. Typical requests include placing the user's product into a competitor-style scene, swapping an old SKU for a new SKU, replacing a generic item in a lifestyle photo, or creating a clean ecommerce composite from a product cutout plus scene reference.

Use this for product swaps. Use `ecommerce-background-replace-images` when there is no target product to replace and only the background changes.

## Inputs

- Required: user's product image. Preserve product identity, shape, color, logo placement, packaging, and distinctive details.
- Required: replacement target or reference scene image, unless the user describes the scene clearly enough to generate it.
- Optional: instruction for which object to replace if the scene contains multiple products.
- Optional: reference constraints such as camera angle, surface, lighting, scale, shadows, and crop.
- Optional: platform, size, format, quality, and output count.

Do not preserve competitor logos, product labels, watermarks, exact ad text, or trade dress from the reference scene.

## Execution

Use `$gpt-image-2` image editing mode via `fusion-api.openai_image_edit_async_submit`. Upload the user's product image and the reference scene image. Put the user's product first, then the scene/reference images.

Prompt structure:

```text
Create a marketplace-ready ecommerce product replacement composite.
Product to insert: preserve image 1 accurately, including shape, color, proportions, logo placement, packaging, and distinctive details.
Reference scene: use image 2 as the scene/composition target.
Replacement instruction: replace <target object> in the scene with the product from image 1.
Integration: match perspective, scale, lighting, shadows, contact points, and camera angle naturally.
Remove or avoid: competitor brands, watermarks, existing product labels, platform badges, ad text, QR codes, phone numbers, unsupported claims.
Composition: realistic ecommerce image, product is clear and sellable, no visual artifacts.
```

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-product-replace-images/<short-product-name>-<timestamp>/` with names like `product-replace-01.png`. Preview when practical and mention the replaced target.

## Failure Handling

- Missing user product image: ask for it.
- Missing reference scene or unclear target object: ask one focused question.
- Reference contains competitor marks: instruct removal or neutralization.
- Product scale/perspective mismatch: retry with stronger integration instructions.
- Connector handle, timeout, auth, billing, upload, or schema failure: follow `$gpt-image-2` guidance and report the exact blocker.