image-ecommerce

image-ecommerce

このスキルは、Starchild におけるすべての e コマース製品撮影リクエストに使用します。

対象: 白背景のヒーローショット、ライフスタイル製品シーン、フラットレイの配置、ディテール/マクロのクローズアップ、パッケージ/開封ショット、グループ/コレクションのディスプレイ、スケール参照画像、季節テーマ(春/夏/秋/冬)、360 度ビュー、比較レイアウト、インフォグラフィック風の機能コールアウト、および Amazon、Shopify、Taobao、Instagram、Xiaohongshu、Etsy、eBay 向けに最適化された画像。

基本原則: 提供されたスクリプトを呼び出してください。プロキシ/課金の配線を再実装しないでください。

image-ecommerce と他の画像スキルの使い分け:

• image-ecommerce → ユーザーが e コマース、カタログ、マーケティング用の製品写真を求めている
• image-edit → ユーザーが既存の画像を編集または変換したい(製品固有ではない)
• image-portrait → ユーザーが顔/本人性を保持したポートレートを求めている
• image-create → ユーザーがテキストから何かを生成したい(製品撮影ではない)
• image-tryon → ユーザーが人物に衣類/アクセサリーを試着させたい

---

1. クイックスタート — 単一の製品写真(最も一般的)

⚠️ 実行コンテキスト — まずこれを読んでください。 以下のコードブロックは Python であり、シェルコマンドではありません。Starchild の bash ツールは /bin/bash -c を実行するため、exec(open(...)) を解析できません — これをそのまま bash コマンドに貼り付けると syntax error near unexpected token 'open' で失敗します。 また、python3 -c 内の exec(open(...)) は NameError: __file__ で失敗します。 これはスクリプトがパス解決に __file__ を使用しているためです。

bash ツール経由で呼び出す場合は、from exports import を伴う python3 - <<'EOF' を使用してください:

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

ヒアドキュメント(<<'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 エンコードして、データ 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 / WeChat では、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、eコマース標準、マーケットプレイスのリスティング
グラデーション	gradient	ヒーローショット、プレミアム感、モダン
スタジオ	studio	プロフェッショナルなカタログ、制御された照明
ナチュラル	natural	アウトドア商品、オーガニックブランド
ライフスタイル	lifestyle	家庭/オフィスのコンテキスト、使用シーン
カラー	colored	ブランドに合わせた配色、鮮やかなマーケティング
テクスチャ	textured	高級商品、大理石/木の表面
透明	transparent	商品の切り抜き、デザイン用 PNG

---

9. プラットフォーム別プリセット

プラットフォーム	アスペクト比	背景	スタイル	主な要件
Amazon	1:1	white	hero	純白背景（RGB 255,255,255）、商品が85%以上を占める、小道具・テキスト・透かしなし、最小1000px（ズーム用は1600px以上）
Shopify	1:1	white	hero	正方形フォーマット、一貫したカタログスタイル、2048x2048を推奨
Taobao	1:1	white	hero	最小800x800、メイン画像は白背景
Instagram	1:1	lifestyle	lifestyle	フィードは1080x1080、ライフスタイルの文脈、視覚的に魅力的
Xiaohongshu	3:4	lifestyle	flat_lay	縦型1080x1440、美しいフラットレイ、テキストオーバーレイ用のスペース
Etsy	4:3	natural	lifestyle	ハンドメイド・職人らしさ、自然な背景
eBay	1:1	white	hero	白背景、商品が明確に見える、ズーム用に最小1600px

---

10. モデル選択ガイド

モデル	キー	速度	品質	最適な用途
NanoPro	nanopro	約25秒	良好	すべてのリクエストのデフォルト。高速なイテレーション。
GPT Image 2	gpt	約150秒	最高	ユーザーが「最高品質」または「ベスト品質」を明示的に求めた場合。複雑なシーン。

判断ルール:

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. 意図認識ガイド

この表を使って、ユーザーのリクエストを正しいスタイル + 背景にマッピングします:

商品リスティング画像

ユーザーの発言	スタイル	背景	備考
"product photo", "listing image", "主图"	hero	white	デフォルトのEコマース
"Amazon listing", "亚马逊主图"	hero	white	platform="amazon" を使用
"Shopify product", "独立站产品图"	hero	white	platform="shopify" を使用
"淘宝主图", "天猫主图"	hero	white	platform="taobao" を使用
"white background", "白底图"	hero	white	標準的なパックショット
"product on white", "纯白背景"	hero	white	Amazonスタイル

ライフスタイルと文脈

ユーザーの発言	スタイル	背景	備考
"lifestyle photo", "场景图"	lifestyle	lifestyle	文脈の中の商品
"product in use", "使用场景"	lifestyle	lifestyle	使用中の商品を表示
"flat lay", "俯拍", "平铺"	flat_lay	textured	真上からの配置
"Instagram product", "小红书产品"	flat_lay	lifestyle	ソーシャルメディアに最適化

ディテールとテクニカル

ユーザーの発言	スタイル	背景	備考
"close-up", "detail shot", "细节图"	detail	studio	マクロ/テクスチャ
"packaging", "包装图", "开箱"	packaging	studio	箱 + 商品
"size comparison", "尺寸对比"	scale	studio	参照オブジェクト付き
"multiple products", "组合图"	group	white	コレクションの表示
"360 view", "多角度"	360_view	white	ターンテーブルスタイル
"comparison", "对比图"	comparison	white	並べて表示
"infographic", "功能标注"	infographic	white	機能の注釈

季節とキャンペーン

ユーザーの発言	スタイル	背景	備考
"spring campaign", "春季"	seasonal_spring	auto	桜、パステルカラー
"summer sale", "夏季"	seasonal_summer	auto	ビーチ、トロピカル
"autumn/fall", "秋季"	seasonal_autumn	auto	金色の葉、暖色
"winter/holiday", "冬季", "圣诞"	seasonal_winter	auto	雪、お祝い

完全な商品セット

ユーザーの発言	関数	備考
"complete set", "全套产品图", "listing images"	product_photo_set()	すべてのアングルをカバーする7枚の画像
"Amazon listing set", "亚马逊全套"	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 / 小紅書（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",
)

複数画像 — バッチ生成

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. ライティングの具体性 — 常にライティングの種類を指定する：

   • スタジオ：「ソフトで拡散したスタジオ照明」「影のない均一な照明」
   • ドラマチック：「ドラマチックなリムライト」「高級感を演出するエッジライト」
   • 自然：「自然な窓辺の光」「ゴールデンアワーの暖かな光」
   • フラット：「フラットで均一な照明」（E コマースの白背景向け）

3. 背景の精度 — 曖昧な背景は低品質な結果を生みます：

   • ❌「素敵な背景」
   • ✅「純白の背景 #FFFFFF、影なし」
   • ✅「朝日の差し込む素朴な木製テーブル」
   • ✅「白からライトグレーへの柔らかなグラデーション」

4. 構図のルール（product-photography スキルより）：

   • ヒーローショット：商品がフレームの 80% を占め、15〜30° のわずかな角度
   • パックショット（Amazon）：商品をど真ん中に配置し、85% 以上を占める
   • フラットレイ：俯瞰視点、整然とした配置
   • グループ：奇数個（3 または 5）、三角形構図

5. 影の種類が重要：

   • 影なし：Amazon／E コマースの要件
   • コンタクトシャドウ：接地感がありながらクリーン
   • ドロップシャドウ：奥行きを加え、プロフェッショナルな印象
   • リフレクション：テック、ラグジュアリー、高級感のある印象

6. 素材とテクスチャ — ディテールショットでは次のように指定します：

   • 「目に見える革の質感とステッチ」
   • 「繊細な反射を伴うヘアライン仕上げの金属」
   • 「柔らかな布地の質感、糸のディテールが見える」

7. プラットフォームへの準拠 — 特定のプラットフォームを対象とする場合：

   • Amazon：純白（RGB 255,255,255）、小道具／テキスト／ウォーターマークなし
   • Instagram：ライフスタイルのコンテキスト、視覚的な魅力
   • 小紅書（Xiaohongshu）：縦長フォーマット、美的センス、テキストオーバーレイ用のスペース

例：カスタムプロンプトの構築

ユーザーのリクエスト：「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. E コマース画像セットガイド

完全な商品リスティングには 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 で利用可能なプリセットを確認してください