image-ecommerce

What this skill does

# image-ecommerce

Use this skill for **all e-commerce product photography requests** on Starchild.

Covers: white-background hero shots, lifestyle product scenes, flat lay arrangements, detail/macro close-ups, packaging/unboxing shots, group/collection displays, scale reference images, seasonal themes (spring/summer/autumn/winter), 360-degree views, comparison layouts, infographic-style feature callouts, and platform-optimized images for Amazon, Shopify, Taobao, Instagram, Xiaohongshu, Etsy, eBay.

**Core principle:** call the provided script. Do not re-implement proxy/billing plumbing.

**When to use image-ecommerce vs other image skills:**
- **image-ecommerce** → user wants PRODUCT PHOTOS for e-commerce, catalogs, or marketing
- **image-edit** → user wants to EDIT or TRANSFORM an existing image (not product-specific)
- **image-portrait** → user wants a portrait with their face/identity preserved
- **image-create** → user wants to CREATE something from text (not product photography)
- **image-tryon** → user wants to try on clothing/accessories on a person

---

## 1. Quick start — single product photo (most common)

```python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/product.jpg",
    style="hero",
    background="white",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}
```

The script reads the local file, base64-encodes it, and sends it to fal.ai as a data URI — no manual URL publishing needed.

## 2. Quick start — public URL

```python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_url="https://example.com/product.jpg",
    style="lifestyle",
    background="natural",
)
```

## 3. Quick start — text-to-image (no product photo)

```python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    prompt="premium wireless bluetooth headphones, matte black finish, over-ear design",
    style="hero",
    background="white",
)
```

When no `product_path` or `product_url` is provided, the script uses the text-to-image endpoint (no `/edit` suffix). A `prompt` describing the product is required in this mode.

## 4. Quick start — platform-optimized

```python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/product.jpg",
    platform="amazon",
)
# Automatically applies: style=hero, background=white, aspect_ratio=1:1
```

## 5. Quick start — complete product image set

```python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo_set(
    product_path="uploads/product.jpg",
    prompt="premium leather wallet",
    platform="amazon",
)
# Generates 7 images: hero, lifestyle, detail, scale, alternate angle, packaging, flat lay
```

### Delivering the result to the user — IMPORTANT

**Never hand the user the raw fal.media URL.** fal serves files with restrictive CSP headers. The only reliable delivery path is the **already-downloaded local file**:

1. Use each image's `local_path` (e.g. `output/images/xxx.png`) — the script always downloads on success.
2. Tell the user the files are saved to `output/images/` and viewable in the workspace file panel.
3. On Web channel, embed inline so the user can preview in chat:
   ```markdown
   ![product](output/images/<filename>.png)
   ```
4. On Telegram / WeChat: send via `send_to_telegram(file_path="output/images/...", message_type="image")` or `send_to_wechat(file_path="output/images/...", message_type="image")`.

---

## 6. Parameters — `product_photo()`

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `product_path` | no | — | Local workspace file path to the product image |
| `product_url` | no | — | Public HTTPS URL of the product image |
| `prompt` | no | — | Custom prompt describing the product or desired photo |
| `style` | no | `"hero"` | Photography style preset (see §7) |
| `background` | no | `"white"` | Background type (see §8) |
| `model` | no | `"nanopro"` | Model: `"nanopro"` (fast ~25s) or `"gpt"` (best quality ~150s) |
| `count` | no | `1` | Number of images to generate (1–8) |
| `aspect_ratio` | no | `"1:1"` | Output ratio: `1:1`, `3:4`, `4:3`, `9:16`, `16:9` |
| `platform` | no | — | Platform preset: `amazon`, `shopify`, `taobao`, `instagram`, `xiaohongshu`, `etsy`, `ebay` |

**Image input rules:**
- Provide `product_path` OR `product_url` for edit mode (transform existing product photo).
- If both are given, `product_path` takes priority.
- Omit both for pure text-to-image generation (requires `prompt`).

**Prompt priority:** `prompt + style/background` (enhanced) > `style + background` templates.

**Platform preset:** When `platform` is set, it overrides default `style`, `background`, and `aspect_ratio` with platform-optimized values — unless you explicitly set them.

---

## 7. Photography styles

### Core product shots

| Style | Key | Best for |
|-------|-----|----------|
| Hero shot | `hero` | Primary listing image, magazine ads, main product display |
| Lifestyle | `lifestyle` | Product in use, editorial, social media |
| Flat lay | `flat_lay` | Instagram, top-down arrangement, catalog |
| Detail close-up | `detail` | Material quality, texture, craftsmanship |
| Packaging | `packaging` | Unboxing experience, brand packaging |
| Group/collection | `group` | Multiple products, variants, bundles |
| Scale reference | `scale` | Size comparison, product in hand |

### Marketing & informational

| Style | Key | Best for |
|-------|-----|----------|
| 360° view | `360_view` | Multi-angle showcase, turntable display |
| Comparison | `comparison` | Side-by-side, before/after, feature highlight |
| Infographic | `infographic` | Feature callouts, specs, dimensions |

### Seasonal campaigns

| Style | Key | Best for |
|-------|-----|----------|
| Spring | `seasonal_spring` | Cherry blossoms, fresh green, pastel |
| Summer | `seasonal_summer` | Beach, sunshine, tropical, vacation |
| Autumn | `seasonal_autumn` | Fall leaves, golden tones, harvest |
| Winter | `seasonal_winter` | Snow, holiday, festive, cozy |

---

## 8. Background types

| Background | Key | Best for |
|------------|-----|----------|
| Pure white | `white` | Amazon, e-commerce standard, marketplace listings |
| Gradient | `gradient` | Hero shots, premium feel, modern |
| Studio | `studio` | Professional catalog, controlled lighting |
| Natural | `natural` | Outdoor products, organic brands |
| Lifestyle | `lifestyle` | Home/office context, in-use scenarios |
| Colored | `colored` | Brand-matching, vibrant marketing |
| Textured | `textured` | Luxury products, marble/wood surface |
| Transparent | `transparent` | Product cutout, PNG for design use |

---

## 9. Platform presets

| Platform | Aspect Ratio | Background | Style | Key Requirements |
|----------|-------------|------------|-------|------------------|
| Amazon | 1:1 | white | hero | Pure white bg (RGB 255,255,255), product fills 85%+, no props/text/watermarks, min 1000px (1600px+ for zoom) |
| Shopify | 1:1 | white | hero | Square format, consistent catalog style, 2048x2048 recommended |
| Taobao | 1:1 | white | hero | 800x800 minimum, white bg for main image |
| Instagram | 1:1 | lifestyle | lifestyle | 1080x1080 feed, lifestyle context, visually appealing |
| Xiaohongshu | 3:4 | lifestyle | flat_lay | 1080x1440 vertical, aesthetic flat lay, text overlay space |
| Etsy | 4:3 | natural | lifestyle | Handmade/artisan feel, natural backgrounds |
| eBay | 1:1 | white | hero | White background, clear product view, 1600px min for zoom |

---

## 10. Model selection guide

| Model | Key | Speed | Quality | Best for |
|-------|-----|-------|---------|----------|
| NanoPro | `nanopro` | ~25s | Good | Default for all requests. Fast iteration. |
| GPT Image 2 | `gpt` | ~150s | Best | When user explicitly asks for "highest quality" or "best quality". Complex sc