image-ecommerce

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)

⚠️ Execution context — read this first. The code blocks below are Python, not shell commands. Starchild's bash tool runs /bin/bash -c, which cannot parse exec(open(...)) — pasting them directly into a bash command will fail with syntax error near unexpected token 'open'. Also, exec(open(...)) inside python3 -c fails with NameError: __file__ because the script uses __file__ for path resolution.

Use python3 - <<'EOF' with from exports import when calling via the bash tool:

python3 - <<'EOF'
import sys
sys.path.insert(0, "skills/image-ecommerce")
from exports import product_photo
result = product_photo(
    product_path="uploads/product.jpg",
    style="hero",
    background="white",
)
print(result)
EOF

The heredoc (<<'EOF') preserves all quotes and newlines — no escaping needed.

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

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

2. 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)

3. 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"

4. 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

5. Shadow types matter:

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

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

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

7. 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