image-ecommerce

image-ecommerce

在 Starchild 上处理所有电商产品摄影请求时，使用此技能。

涵盖：白底主图、生活方式产品场景、平铺摆拍、细节／微距特写、包装／开箱照片、组合／系列展示、尺寸参照图、季节主题（春／夏／秋／冬）、360 度视图、对比布局、信息图式功能说明，以及针对 Amazon、Shopify、Taobao、Instagram、小红书、Etsy、eBay 优化的图片。

**核心原则：**调用提供的脚本。不要重新实现代理／计费流程。

何时使用 image-ecommerce，而不是其他图片技能：

• image-ecommerce → 用户需要用于电商、商品目录或营销的产品照片
• image-edit → 用户需要编辑或转换现有图片（非产品专用）
• image-portrait → 用户需要保留其面部／身份特征的肖像
• image-create → 用户想通过文本创作内容（非产品摄影）
• image-tryon → 用户想让某人试穿衣物／配饰

---

1. 快速开始 — 单张产品照片（最常见）

⚠️ 执行环境 — 请先阅读。 以下代码块是 Python，不是 Shell 命令。Starchild 的 bash 工具 运行 /bin/bash -c，无法解析 exec(open(...))——直接将其粘贴到 bash 命令中 会因 syntax error near unexpected token 'open' 而失败。 此外，在 python3 -c 中使用 exec(open(...)) 会因脚本使用 __file__ 解析路径而报错 NameError: __file__。

通过 bash 工具调用时，请使用 python3 - <<'EOF' 和 from exports import：

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

Here 文档（<<'EOF'）会保留所有引号和换行，无需转义。

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/..."}], ...}

脚本会读取本地文件，将其编码为 base64，然后以 data URI 的形式发送给 fal.ai——无需手动发布 URL。

2. 快速开始 — 公共 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. 快速开始 — 文本生成图像（无产品照片）

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",
)

如果未提供 product_path 或 product_url，脚本会使用文本生成图像端点（不带 /edit 后缀）。在此模式下，必须提供描述产品的 prompt。

4. 快速开始 — 平台优化

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. 快速开始 — 完整产品图片集

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

向用户交付结果 — 重要

绝不要将 fal.media 原始 URL 交给用户。 fal 提供的文件带有严格的 CSP 标头。唯一可靠的交付方式是使用已下载到本地的文件：

1. 使用每张图片的 local_path（例如 output/images/xxx.png）——脚本成功后始终会下载图片。
2. 告知用户文件已保存到 output/images/，可在工作区文件面板中查看。
3. 在 Web 频道中，将图片内嵌，以便用户在聊天中预览：

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

4. 在 Telegram／微信中，通过 send_to_telegram(file_path="output/images/...", message_type="image") 或 send_to_wechat(file_path="output/images/...", message_type="image") 发送。

---

6. 参数 — product_photo()

参数	必填	默认值	描述
product_path	否	—	产品图片的本地工作区文件路径
product_url	否	—	产品图片的公开 HTTPS URL
prompt	否	—	描述产品或所需照片的自定义提示词
style	否	"hero"	摄影风格预设（参见 §7）
background	否	"white"	背景类型（参见 §8）
model	否	"nanopro"	模型："nanopro"（快速，约 25 秒）或 "gpt"（质量最佳，约 150 秒）
count	否	1	要生成的图片数量（1–8）
aspect_ratio	否	"1:1"	输出宽高比：1:1、3:4、4:3、9:16、16:9
platform	否	—	平台预设：amazon、shopify、taobao、instagram、xiaohongshu、etsy、ebay

图片输入规则：

• 编辑模式（转换现有产品照片）需提供 product_path 或 product_url。
• 如果两者都提供，优先使用 product_path。
• 若要纯文本生成图片，则两者都不提供（需设置 prompt）。

提示词优先级： prompt + style/background（增强）> style + background 模板。

平台预设： 设置 platform 后，将使用针对该平台优化的值覆盖默认的 style、background 和 aspect_ratio，除非你明确设置这些参数。

---

7. 摄影风格

核心产品照片

风格	键	适用场景
主图	hero	商品主图、杂志广告、产品主展示
生活方式	lifestyle	产品使用场景、编辑内容、社交媒体
平铺摆拍	flat_lay	Instagram、俯拍摆放、产品目录
细节特写	detail	材质品质、纹理、工艺
包装	packaging	开箱体验、品牌包装
组合/系列	group	多款产品、不同变体、套装
尺寸参照	scale	尺寸对比、手持产品

营销与信息展示

风格	键	适用场景
360° 视图	360_view	多角度展示、转盘展示
对比	comparison	并排对比、前后对比、功能亮点
信息图	infographic	功能标注、规格、尺寸

季节性营销活动

风格	键	适用场景
春季	seasonal_spring	樱花、新绿、柔和色彩
夏季	seasonal_summer	海滩、阳光、热带风情、度假
秋季	seasonal_autumn	秋叶、金色调、丰收
冬季	seasonal_winter	雪景、节日、喜庆氛围、温馨舒适

---

8. 背景类型

背景	键	适用场景
纯白	white	Amazon、电商标准、 marketplace 商品列表
渐变	gradient	主图、高级质感、现代风格
影棚	studio	专业产品目录、可控光线
自然	natural	户外产品、有机品牌
生活方式	lifestyle	家居/办公环境、使用场景
彩色	colored	匹配品牌、鲜艳的营销素材
纹理	textured	奢侈品、大理石/木质表面
透明	transparent	产品抠图、用于设计的 PNG

---

9. 平台预设

平台	宽高比	背景	风格	关键要求
Amazon	1:1	白色	hero	纯白背景（RGB 255,255,255），产品占比 85% 以上，不得有道具/文字/水印，最小尺寸 1000px（缩放查看建议 1600px 以上）
Shopify	1:1	白色	hero	正方形格式，目录风格一致，建议使用 2048x2048
Taobao	1:1	白色	hero	最小尺寸 800x800，主图使用白色背景
Instagram	1:1	生活方式	lifestyle	信息流图片尺寸为 1080x1080，展现生活场景，视觉上吸引人
Xiaohongshu	3:4	生活方式	flat_lay	竖版尺寸为 1080x1440，美观的平铺构图，并留出文字叠加空间
Etsy	4:3	自然	lifestyle	具有手工/匠人质感，使用自然背景
eBay	1:1	白色	hero	白色背景，清晰展示产品，缩放查看时最小尺寸为 1600px

---

10. 模型选择指南

模型	键	速度	质量	适用场景
NanoPro	nanopro	~25s	良好	所有请求的默认选择。适合快速迭代。
GPT Image 2	gpt	~150s	最佳	用户明确要求“最高质量”或“最佳质量”时使用。适用于复杂场景。

决策规则：

1. 默认： 始终使用 nanopro，除非用户明确要求更高质量。
2. 使用 gpt 的情况： 用户表示“最高质量”“最佳质量”“高级”，或者场景非常复杂且包含许多具体细节。
3. 使用 nanopro 的情况： 用户希望快速获得结果、正在迭代不同风格，或需要生成多张图片。

# 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. 意图识别指南

使用此表将用户请求映射到正确的风格和背景：

产品刊登图片

用户表述	风格	背景	备注
“产品照片”“刊登图片”“主图”	hero	white	默认电商图片
“Amazon 刊登图片”“亚马逊主图”	hero	white	使用 platform="amazon"
“Shopify 产品”“独立站产品图”	hero	white	使用 platform="shopify"
“淘宝主图”“天猫主图”	hero	white	使用 platform="taobao"
“白色背景”“白底图”	hero	white	标准商品照
“白色背景上的产品”“纯白背景”	hero	white	Amazon 风格

生活方式与场景

用户表述	风格	背景	备注
“生活方式照片”“场景图”	lifestyle	lifestyle	展示场景中的产品
“使用中的产品”“使用场景”	lifestyle	lifestyle	展示产品的使用过程
“平铺构图”“俯拍”“平铺”	flat_lay	textured	俯拍式摆放
“Instagram 产品”“小红书产品”	flat_lay	lifestyle	针对社交媒体优化

细节与技术展示

用户表述	风格	背景	备注
“特写”“细节镜头”“细节图”	detail	studio	微距/纹理
“包装”“包装图”“开箱”	packaging	studio	包装盒 + 产品
“尺寸对比”“尺寸对比”	scale	studio	带有参照物
“多款产品”“组合图”	group	white	系列产品展示
“360 度视图”“多角度”	360_view	white	转台式展示
“比较”“对比图”	comparison	white	并排展示
“信息图”“功能标注”	infographic	white	功能标注

季节与营销活动

用户表述	风格	背景	备注
“春季活动”“春季”	seasonal_spring	auto	樱花、柔和色调
“夏季促销”“夏季”	seasonal_summer	auto	海滩、热带风情
“秋季/秋天”“秋季”	seasonal_autumn	auto	金色树叶、温暖氛围
“冬季/节日”“冬季”“圣诞”	seasonal_winter	auto	雪景、节日氛围

完整产品套图

用户表述	函数	备注
“完整套图”“全套产品图”“刊登图片”	product_photo_set()	7 张图片，涵盖所有角度
“Amazon 刊登套图”“亚马逊全套”	product_photo_set(platform="amazon")	针对平台优化的套图

---

12. 按场景分类的使用示例

Amazon 商品列表 — 白色背景主图

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

生活方式产品照片

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",
)

产品细节特写

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",
)

季节性营销活动 — 冬季假日

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",
)

文生图 — 根据描述生成产品图

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",
)

Instagram / 小红书平铺图

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",
)

多张图片 — 批量生成

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

完整产品图片集

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. 提示词工程最佳实践

产品摄影提示词结构

每条有效的产品照片提示词都应包含以下要素：

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

核心原则（源自 product-photography、eachlabs-product-visuals、image-create 技能）

1. 产品保真至关重要 — 编辑现有产品图片时：

   • 始终强调“保持产品原样”
   • 保留形状、颜色、品牌标识和细节
   • 仅更改背景／环境／光线

2. 明确指定光线 — 始终注明光线类型：

   • 影棚： “柔和的漫射影棚灯光”、“光线均匀，无阴影”
   • 戏剧性： “戏剧性的轮廓光”、“边缘光，营造高级感”
   • 自然： “自然窗光”、“温暖的黄金时段光线”
   • 平光： “均匀的平光”（适用于电商白色背景）

3. 精准描述背景 — 模糊的背景描述会导致效果不佳：

   • ❌ “好看的背景”
   • ✅ “纯白背景 #FFFFFF，无阴影”
   • ✅ “带有晨光的乡村风木桌”
   • ✅ “从白色到浅灰色的柔和渐变”

4. 构图规则（来自 product-photography 技能）：

   • 主图：产品占画面 80%，角度略倾斜 15-30°
   • 商品图（Amazon）：产品正中，画面占比至少 85%
   • 平铺图：俯拍视角，排列整齐
   • 组合图：使用奇数个产品（3 或 5 个），采用三角形构图

5. 阴影类型很重要：

   • 无阴影：符合 Amazon／电商要求
   • 接触阴影：使产品有落地感，同时保持干净
   • 投影：增加立体感，显得专业
   • 倒影：营造科技感、奢华感和高级感

6. 材质和纹理 — 拍摄细节图时，请注明：

   • “清晰可见的皮革纹理和缝线”
   • “拉丝金属表面，带有细腻的反光”
   • “柔软的织物纹理，可见纤维细节”

7. 符合平台规范 — 面向特定平台时：

   • Amazon：纯白（RGB 255,255,255），无道具／文字／水印
   • Instagram：生活方式场景，视觉效果吸引人
   • 小红书：竖版格式，风格美观，并留出叠加文字的空间

示例：构建自定义提示词

用户请求：“我需要一张用于 Amazon 的皮革钱包主图”

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

脚本会自动构建：

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. 电商图片集指南

完整的产品列表需要 7-9 张图片。使用 product_photo_set() 自动生成，也可以分别创建单张图片：

位置	图片类型	风格	背景	用途
1	主图／商品图	hero	white	列表主图
2	生活方式图	lifestyle	lifestyle	展示产品的使用场景／环境
3	细节特写	detail	studio	展示材质质量和工艺
4	尺寸参照	scale	studio	展示手持尺寸或与已知物品的尺寸对比
5	其他角度	hero	white	背面或侧面视图
6	包装图	packaging	studio	展示开箱体验
7	平铺图	flat_lay	textured	展示排列构图
8	信息图	infographic	white	展示尺寸、规格和功能
9	季节性图片	seasonal_*	auto	特定营销活动

---

15. 错误处理

脚本会返回结构化结果。请始终检查 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')}")

常见错误：

• "File not found" — 检查 product_path
• "Unsupported image format" — 使用 JPG、PNG 或 WebP
• "Image too large" — 最大 10 MB
• "Either a product image or a prompt is required" — 请提供 product_path/product_url 或 prompt
• "Unknown style/background" — 请查看 §7/§8 中可用的预设