| name | image-ecommerce |
| version | 1.0.4 |
| description | E-commerce product photography: white-background hero shots, lifestyle scenes, flat lay, detail close-ups, packaging shots, group/collection displays, scale references, seasonal/holiday themes, 360-degree views, comparison layouts, infographics, and platform-optimized images (Amazon, Shopify, Taobao, Instagram, Xiaohongshu, Etsy, eBay).
Use when generating professional product photos for e-commerce listings, catalogs, or marketing (e.g. product hero shot, Amazon listing image, lifestyle product photo, product on white background, product detail close-up, seasonal product campaign).
|
| metadata | {"starchild":{"emoji":"🛍️","skillKey":"image-ecommerce"}} |
| user-invocable | true |
| disable-model-invocation | false |
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",
)
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",
)
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",
)
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
local_path (e.g. output/images/xxx.png) — the script always downloads on success.
- Tell the user the files are saved to
output/images/ and viewable in the workspace file panel.
- On Web channel, embed inline so the user can preview in chat:
- 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 scenes. |
Decision rules:
- Default: always use
nanopro unless the user explicitly requests higher quality.
- Use
gpt when: user says "highest quality", "best quality", "premium", or the scene is very complex with many specific details.
- Use
nanopro when: user wants fast results, is iterating on styles, or generating multiple images.
result = product_photo(product_path="product.jpg", style="hero")
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", "主图" | hero | white | Default e-commerce |
| "Amazon listing", "亚马逊主图" | hero | white | Use platform="amazon" |
| "Shopify product", "独立站产品图" | hero | white | Use platform="shopify" |
| "淘宝主图", "天猫主图" | hero | white | Use platform="taobao" |
| "white background", "白底图" | hero | white | Standard packshot |
| "product on white", "纯白背景" | hero | white | Amazon-style |
Lifestyle & context
| User says | Style | Background | Notes |
|---|
| "lifestyle photo", "场景图" | lifestyle | lifestyle | Product in context |
| "product in use", "使用场景" | lifestyle | lifestyle | Show product being used |
| "flat lay", "俯拍", "平铺" | flat_lay | textured | Top-down arrangement |
| "Instagram product", "小红书产品" | flat_lay | lifestyle | Social media optimized |
Detail & technical
| User says | Style | Background | Notes |
|---|
| "close-up", "detail shot", "细节图" | detail | studio | Macro/texture |
| "packaging", "包装图", "开箱" | packaging | studio | Box + product |
| "size comparison", "尺寸对比" | scale | studio | With reference object |
| "multiple products", "组合图" | group | white | Collection display |
| "360 view", "多角度" | 360_view | white | Turntable style |
| "comparison", "对比图" | comparison | white | Side by side |
| "infographic", "功能标注" | infographic | white | Feature callouts |
Seasonal & campaign
| User says | Style | Background | Notes |
|---|
| "spring campaign", "春季" | seasonal_spring | auto | Cherry blossoms, pastel |
| "summer sale", "夏季" | seasonal_summer | auto | Beach, tropical |
| "autumn/fall", "秋季" | seasonal_autumn | auto | Golden leaves, warm |
| "winter/holiday", "冬季", "圣诞" | seasonal_winter | auto | Snow, festive |
Complete product set
| User says | Function | Notes |
|---|
| "complete set", "全套产品图", "listing images" | product_photo_set() | 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
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,
)
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",
)
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"
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:
| Position | Image Type | Style | Background | Purpose |
|---|
| 1 | Hero / packshot | hero | white | Primary listing image |
| 2 | Lifestyle | lifestyle | lifestyle | Product in use/context |
| 3 | Detail close-up | detail | studio | Material quality, craftsmanship |
| 4 | Scale reference | scale | studio | Size in hand or next to known object |
| 5 | Alternate angle | hero | white | Back or side view |
| 6 | Packaging | packaging | studio | Unboxing experience |
| 7 | Flat lay | flat_lay | textured | Arranged composition |
| 8 | Infographic | infographic | white | Dimensions, specs, features |
| 9 | Seasonal | seasonal_* | auto | Campaign-specific |
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
