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
or
is provided, the script uses the text-to-image endpoint (no
suffix). A
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:
- Use each image's (e.g. ) — the script always downloads on success.
- Tell the user the files are saved to and viewable in the workspace file panel.
- On Web channel, embed inline so the user can preview in chat:
markdown
- On Telegram / WeChat: send via
send_to_telegram(file_path="output/images/...", message_type="image")
send_to_wechat(file_path="output/images/...", message_type="image")
6. Parameters —
| Parameter | Required | Default | Description |
|---|
| no | — | Local workspace file path to the product image |
| no | — | Public HTTPS URL of the product image |
| no | — | Custom prompt describing the product or desired photo |
| no | | Photography style preset (see §7) |
| no | | Background type (see §8) |
| no | | Model: (fast ~25s) or (best quality ~150s) |
| no | | Number of images to generate (1–8) |
| no | | Output ratio: , , , , |
| no | — | Platform preset: , , , , , , |
Image input rules:
- Provide OR for edit mode (transform existing product photo).
- If both are given, takes priority.
- Omit both for pure text-to-image generation (requires ).
Prompt priority: prompt + style/background
(enhanced) >
templates.
Platform preset: When
is set, it overrides default
,
, and
with platform-optimized values — unless you explicitly set them.
7. Photography styles
Core product shots
| Style | Key | Best for |
|---|
| Hero shot | | Primary listing image, magazine ads, main product display |
| Lifestyle | | Product in use, editorial, social media |
| Flat lay | | Instagram, top-down arrangement, catalog |
| Detail close-up | | Material quality, texture, craftsmanship |
| Packaging | | Unboxing experience, brand packaging |
| Group/collection | | Multiple products, variants, bundles |
| Scale reference | | Size comparison, product in hand |
Marketing & informational
| Style | Key | Best for |
|---|
| 360° view | | Multi-angle showcase, turntable display |
| Comparison | | Side-by-side, before/after, feature highlight |
| Infographic | | Feature callouts, specs, dimensions |
Seasonal campaigns
| Style | Key | Best for |
|---|
| Spring | | Cherry blossoms, fresh green, pastel |
| Summer | | Beach, sunshine, tropical, vacation |
| Autumn | | Fall leaves, golden tones, harvest |
| Winter | | Snow, holiday, festive, cozy |
8. Background types
| Background | Key | Best for |
|---|
| Pure white | | Amazon, e-commerce standard, marketplace listings |
| Gradient | | Hero shots, premium feel, modern |
| Studio | | Professional catalog, controlled lighting |
| Natural | | Outdoor products, organic brands |
| Lifestyle | | Home/office context, in-use scenarios |
| Colored | | Brand-matching, vibrant marketing |
| Textured | | Luxury products, marble/wood surface |
| 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 | | ~25s | Good | Default for all requests. Fast iteration. |
| GPT Image 2 | | ~150s | Best | When user explicitly asks for "highest quality" or "best quality". Complex scenes. |
Decision rules:
- Default: always use unless the user explicitly requests higher quality.
- Use when: user says "highest quality", "best quality", "premium", or the scene is very complex with many specific details.
- Use when: user wants fast results, is iterating on styles, or generating multiple images.
python
# 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
| User says | Style | Background | Notes |
|---|
| "product photo", "listing image", "主图" | | | Default e-commerce |
| "Amazon listing", "亚马逊主图" | | | Use |
| "Shopify product", "独立站产品图" | | | Use |
| "淘宝主图", "天猫主图" | | | Use |
| "white background", "白底图" | | | Standard packshot |
| "product on white", "纯白背景" | | | Amazon-style |
Lifestyle & context
| User says | Style | Background | Notes |
|---|
| "lifestyle photo", "场景图" | | | Product in context |
| "product in use", "使用场景" | | | Show product being used |
| "flat lay", "俯拍", "平铺" | | | Top-down arrangement |
| "Instagram product", "小红书产品" | | | Social media optimized |
Detail & technical
| User says | Style | Background | Notes |
|---|
| "close-up", "detail shot", "细节图" | | | Macro/texture |
| "packaging", "包装图", "开箱" | | | Box + product |
| "size comparison", "尺寸对比" | | | With reference object |
| "multiple products", "组合图" | | | Collection display |
| "360 view", "多角度" | | | Turntable style |
| "comparison", "对比图" | | | Side by side |
| "infographic", "功能标注" | | | Feature callouts |
Seasonal & campaign
| User says | Style | Background | Notes |
|---|
| "spring campaign", "春季" | | auto | Cherry blossoms, pastel |
| "summer sale", "夏季" | | auto | Beach, tropical |
| "autumn/fall", "秋季" | | auto | Golden leaves, warm |
| "winter/holiday", "冬季", "圣诞" | | auto | Snow, festive |
Complete product set
| User says | Function | Notes |
|---|
| "complete set", "全套产品图", "listing images" | | 7 images covering all angles |
| "Amazon listing set", "亚马逊全套" | product_photo_set(platform="amazon")
| Platform-optimized set |
12. Usage examples by scenario
Amazon listing — white background hero shot
python
exec(open('skills/image-ecommerce/product_photo.py').read())
result = product_photo(
product_path="uploads/headphones.jpg",
platform="amazon",
)
Lifestyle product photo
python
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
python
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
python
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
python
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
python
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
python
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
python
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)
-
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
-
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)
-
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"
-
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
-
Shadow types matter:
- No shadow: Amazon/e-commerce requirements
- Contact shadow: grounded but clean
- Drop shadow: adds depth, professional
- Reflection: tech, luxury, premium feel
-
Material and texture — for detail shots, specify:
- "visible leather grain and stitching"
- "brushed metal finish with subtle reflections"
- "soft fabric texture, thread detail visible"
-
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"
python
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
for automatic generation, or create individual shots:
| Position | Image Type | Style | Background | Purpose |
|---|
| 1 | Hero / packshot | | | Primary listing image |
| 2 | Lifestyle | | | Product in use/context |
| 3 | Detail close-up | | | Material quality, craftsmanship |
| 4 | Scale reference | | | Size in hand or next to known object |
| 5 | Alternate angle | | | Back or side view |
| 6 | Packaging | | | Unboxing experience |
| 7 | Flat lay | | | Arranged composition |
| 8 | Infographic | | | Dimensions, specs, features |
| 9 | Seasonal | | auto | Campaign-specific |
15. Error handling
The script returns structured results. Always check
:
python
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:
- — check the product_path
"Unsupported image format"
- — max 10 MB
"Either a product image or a prompt is required"
"Unknown style/background"