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)

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

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)

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

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

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:

   ![product](output/images/<filename>.png)

1. 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()

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

Marketing & informational

Seasonal campaigns

---

8. Background types

---

9. Platform presets

---

10. Model selection guide

Decision rules:

1. Default: always use nanopro unless the user explicitly requests higher quality.
2. Use gpt when: user says "highest quality", "best quality", "premium", or the scene is very complex with many specific details.
3. Use nanopro when: user wants fast results, is iterating on styles, or generating multiple images.

# Default (fast)
result = product_photo(product_path="product.jpg", style="hero")

# High quality (user requested)
result = product_photo(product_path="product.jpg", style="hero", model="gpt")

---

11. Intent recognition guide

Use this table to map user requests to the correct style + background:

Product listing images

Lifestyle & context

Detail & technical

Seasonal & campaign

Complete product set

---

12. Usage examples by scenario

Amazon listing — white background hero shot

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/headphones.jpg",
    platform="amazon",
)

Lifestyle product photo

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/coffee_mug.jpg",
    style="lifestyle",
    background="lifestyle",
    prompt="premium coffee mug on rustic wooden table beside an open book, morning sunlight",
)

Product detail close-up

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/leather_bag.jpg",
    style="detail",
    background="studio",
    prompt="extreme close-up of leather stitching and grain texture",
)

Seasonal campaign — winter holiday

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/candle.jpg",
    style="seasonal_winter",
    prompt="luxury scented candle in cozy holiday setting with pine branches and warm glow",
)

Text-to-image — generate product from description

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    prompt="sleek minimalist smartwatch with black silicone band and OLED display showing time",
    style="hero",
    background="gradient",
    model="gpt",
)

Flat lay for Instagram / Xiaohongshu

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/skincare_set.jpg",
    style="flat_lay",
    background="textured",
    platform="xiaohongshu",
)

Multiple images — batch generation

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
    product_path="uploads/sneakers.jpg",
    style="hero",
    background="white",
    count=4,
)
# Generates 4 variations of the hero shot

Complete product image set

exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo_set(
    product_path="uploads/wallet.jpg",
    prompt="premium leather bifold wallet",
    platform="amazon",
)
# result -> {"success": True, "sets": [...], "total_images": 7, ...}
# Generates: hero, lifestyle, detail, scale, alternate angle, packaging, flat lay

---

13. Prompt engineering best practices

The product photography prompt structure

Every effective product photo prompt should include these elements:

[product description], [photography style], [lighting], [background/surface], [composition], [quality modifiers]

Key principles (derived from product-photography, eachlabs-product-visuals, image-create skills)

1. Product preservation is critical — when editing an existing product image:

• Always emphasize "keep the product exactly as it is"
• Preserve shape, color, branding, and details
• Only change the background/context/lighting

1. Lighting specificity — always specify lighting type:

• Studio: "soft diffused studio lighting", "even lighting with no shadows"
• Dramatic: "dramatic rim lighting", "edge light for premium feel"
• Natural: "natural window light", "golden hour warm light"
• Flat: "flat even lighting" (for e-commerce white background)

1. Background precision — vague backgrounds produce poor results:

• ❌ "nice background"
• ✅ "pure white background #FFFFFF, no shadows"
• ✅ "rustic wooden table with morning sunlight"
• ✅ "soft gradient from white to light grey"

1. Composition rules (from product-photography skill):

• Hero shot: product fills 80% of frame, slight 15-30° angle
• Packshot (Amazon): product dead center, fills 85%+
• Flat lay: bird's eye view, organized arrangement
• Group: odd numbers (3 or 5), triangle composition

1. Shadow types matter:

• No shadow: Amazon/e-commerce requirements
• Contact shadow: grounded but clean
• Drop shadow: adds depth, professional
• Reflection: tech, luxury, premium feel

1. Material and texture — for detail shots, specify:

• "visible leather grain and stitching"
• "brushed metal finish with subtle reflections"
• "soft fabric texture, thread detail visible"

1. Platform compliance — when targeting a specific platform:

• Amazon: pure white (RGB 255,255,255), no props/text/watermarks
• Instagram: lifestyle context, visually appealing
• Xiaohongshu: vertical format, aesthetic, text overlay space

Example: building a custom prompt

User request: "I need a hero shot of my leather wallet for Amazon"

result = product_photo(
    product_path="uploads/wallet.jpg",
    platform="amazon",
    prompt="premium leather bifold wallet, rich brown color, slight angle showing card slots",
)

The script automatically builds:

Transform this product image into a professional e-commerce photo.
Keep the product exactly as it is — preserve its shape, color, details, and branding.
premium leather bifold wallet, rich brown color, slight angle showing card slots.
Photography style: professional product hero shot, clean composition, studio lighting...
Background: pure white background #FFFFFF, clean, e-commerce standard, no shadows.

---

14. E-commerce image set guide

A complete product listing needs 7-9 images. Use product_photo_set() for automatic generation, or create individual shots:

---

15. Error handling

The script returns structured results. Always check success:

result = product_photo(product_path="uploads/product.jpg")
if result["success"]:
    for img in result["images"]:
        print(f"Saved: {img['local_path']}")
else:
    print(f"Error: {result.get('error')}")

Common errors:

• "File not found" — check the product_path
• "Unsupported image format" — use JPG, PNG, or WebP
• "Image too large" — max 10 MB
• "Either a product image or a prompt is required" — provide product_path/product_url or prompt
• "Unknown style/background" — check available presets in §7/§8