image-tryon

image-tryon

Starchild 上のすべてのバーチャル試着リクエストでこのスキルを使用します。

対象: 衣類の試着、アクセサリーの試着、ヘアスタイルのプレビュー、メイクのプレビュー、眼鏡の試着、帽子の試着、靴の試着、時計の試着。

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

image-edit との主な違い: 試着には常に2 枚の画像が必要です — 人物の写真と衣類/アイテムの写真です。

---

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-tryon")
from exports import try_on
result = try_on(
    person_path="uploads/person.jpg",
    garment_path="uploads/dress.jpg",
    category="clothing",
)
print(result)
EOF

ヒアドキュメント（<<'EOF'）はすべての引用符と改行を保持します — エスケープは不要です。

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person.jpg",
    garment_path="uploads/dress.jpg",
    category="clothing",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}

スクリプトは両方のローカルファイルを読み取り、base64 エンコードして、データ URI として fal.ai に送信します — 手動での URL 公開は不要です。

2. クイックスタート — URL 入力

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_url="https://example.com/person.jpg",
    garment_url="https://example.com/jacket.jpg",
    category="clothing",
)

3. クイックスタート — 眼鏡の試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/face.jpg",
    garment_path="uploads/sunglasses.jpg",
    category="glasses",
)

ユーザーへの結果の配信 — 重要

ユーザーに生の fal.media URL を決して渡さないでください。 fal は制限的な CSP ヘッダーでファイルを配信します。唯一信頼できる配信経路は、すでにダウンロード済みのローカルファイルです:

1. 各画像の local_path（例: output/images/xxx.png）を使用します — スクリプトは成功時に必ずダウンロードします。
2. ファイルは output/images/ に保存され、ワークスペースのファイルパネルで閲覧できることをユーザーに伝えます。
3. Web チャネルでは、ユーザーがチャット内でプレビューできるようにインラインで埋め込みます:

   ![try-on result](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") 経由で送信します。

---

4. パラメータ

パラメータ	必須	デフォルト	説明
person_path	はい*	—	人物の写真へのローカルワークスペースファイルパス
person_url	はい*	—	人物の写真の公開 HTTPS URL
garment_path	はい*	—	衣類/アイテムの写真へのローカルワークスペースファイルパス
garment_url	はい*	—	衣類/アイテムの写真の公開 HTTPS URL
category	いいえ	"clothing"	試着カテゴリキー（§5 参照）
prompt	いいえ	None	カスタムプロンプト — 設定するとカテゴリのデフォルトを上書きします
model	いいえ	"nanopro"	モデル: "nanopro"（高速 ~25 秒）または "gpt"（最高品質 ~150 秒）
aspect_ratio	いいえ	"3:4"	出力比率: 1:1、3:4、4:3、9:16、16:9

画像入力ルール:

• 人物画像: person_path または person_url のいずれかを指定します（いずれかが必須）。
• 衣類/アイテム画像: garment_path または garment_url のいずれかを指定します（いずれかが必須）。
• 同じ画像に対してパスと URL の両方が指定された場合、パスが優先されます。
• 両方の画像が必須です — 試着は 1 枚の画像だけでは機能しません。

プロンプトの優先順位: prompt（完全上書き）> category のデフォルトプロンプト。

---

5. 試着カテゴリ

意図認識 — ユーザーの発言 → 使用するカテゴリ

ユーザーの発言	カテゴリ	キー
「このドレス/シャツ/ジャケット/コーデを試着して」	衣類	clothing
「このネックレス/スカーフ/バッグを身につけて」	アクセサリー	accessory
「このヘアスタイル/髪色で見せて」	ヘアスタイル	hairstyle
「このメイク/リップのルックを適用して」	メイク	makeup
「このメガネ/サングラスを試着して」	メガネ	glasses
「この帽子/キャップ/ニット帽をかぶせて」	帽子	hat
「この靴/スニーカー/ブーツを試着して」	靴	shoes
「この時計を手首につけて」	腕時計	watch

カテゴリの詳細

カテゴリ	キー	最適な用途	写真の要件
衣類	clothing	シャツ、ドレス、ジャケット、パンツ、コート、全身コーデ	全身または上半身の人物写真
アクセサリー	accessory	スカーフ、バッグ、ベルト、ジュエリー、ネックレス、イヤリング	該当する身体部位が見えること
ヘアスタイル	hairstyle	ヘアカット、髪色、スタイリングの変更	顔・頭がはっきり写った写真
メイク	makeup	リップ、アイシャドウ、ファンデーション、チーク、フルメイク	顔の鮮明なクローズアップ
メガネ	glasses	度付きメガネ、サングラス、リーディンググラス	顔がはっきり写った正面の写真
帽子	hat	キャップ、ニット帽、フェドラ、サンハット、ヘルメット	頭と肩が見えること
靴	shoes	スニーカー、ヒール、ブーツ、サンダル、ローファー	全身または下半身の写真
腕時計	watch	アナログ、スマートウォッチ、高級時計	手首・腕が見えること

---

6. モデル選択ガイド

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

判断ルール:

1. デフォルト: ユーザーが明示的に高品質を要求しない限り、常に nanopro を使用します。
2. gpt を使用する場合: ユーザーが「最高品質」、「ベスト品質」、「プレミアム」と言った場合、または結果が業務用途でフォトリアルである必要がある場合。
3. nanopro を使用する場合: ユーザーが高速な結果を求めている場合、複数のアイテムを試している場合、またはルックを反復している場合。

# Default (fast)
result = try_on(person_path="me.jpg", garment_path="dress.jpg", category="clothing")

# High quality (user requested)
result = try_on(person_path="me.jpg", garment_path="dress.jpg", category="clothing", model="gpt")

---

7. カテゴリ別の使用例

衣類の試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person_fullbody.jpg",
    garment_path="uploads/summer_dress.jpg",
    category="clothing",
)

アクセサリーの試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/portrait.jpg",
    garment_path="uploads/gold_necklace.jpg",
    category="accessory",
)

ヘアスタイルのプレビュー

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/face.jpg",
    garment_path="uploads/bob_hairstyle.jpg",
    category="hairstyle",
)

メイクのプレビュー

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/face_closeup.jpg",
    garment_path="uploads/evening_makeup.jpg",
    category="makeup",
)

メガネの試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/face_front.jpg",
    garment_path="uploads/aviator_sunglasses.jpg",
    category="glasses",
)

帽子の試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/head_shoulders.jpg",
    garment_path="uploads/fedora_hat.jpg",
    category="hat",
)

靴の試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person_fullbody.jpg",
    garment_path="uploads/white_sneakers.jpg",
    category="shoes",
)

腕時計の試着

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/wrist_photo.jpg",
    garment_path="uploads/luxury_watch.jpg",
    category="watch",
)

カスタムプロンプト（デフォルトを上書き）

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person.jpg",
    garment_path="uploads/vintage_jacket.jpg",
    category="clothing",
    prompt="The person is wearing the vintage leather jacket from the second image, styled with a casual street fashion look. Keep the person's face and body exactly the same. Add realistic leather texture and natural draping.",
)

異なるアスペクト比

exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person.jpg",
    garment_path="uploads/outfit.jpg",
    category="clothing",
    aspect_ratio="9:16",  # Full-length portrait
)

---

8. 写真の要件 — ベストプラクティス

人物写真のガイドライン

カテゴリ	推奨する写真の種類	ヒント
衣類	全身、正面	腕を体から少し離し、自然なポーズ
アクセサリー	該当する身体部位が見えること	アクセサリーをつける部位に良好な照明
ヘアスタイル	頭・顔がはっきり、正面または斜め45度	髪をまとめるか、現在のスタイルがはっきり見えること
メイク	顔のクローズアップ、正面	素顔、均一で良好な照明、濃いメイクなし
メガネ	顔が正面、目が見えること	現在メガネをかけていないこと、目の周りがはっきりしていること
帽子	頭と肩、正面	現在帽子をかぶっていないこと、髪が見えること
靴	全身または脚・足が見えること	立ったポーズ、現在の靴が見えること
腕時計	手首・前腕が見えること	素肌の手首、または現在の時計が見えること

写真品質の一般的なルール

1. 照明: 明るく均一な照明が最適です。顔・体への強い影は避けてください。
2. 解像度: 1024×1024 以上を推奨します。低解像度の写真は結果が悪くなります。
3. 角度: ほとんどのカテゴリでは正面からの写真が最適です。
4. 背景: どのような背景でも機能しますが、きれいな背景ほどきれいな結果が得られます。
5. ポーズ: 自然でリラックスしたポーズ。極端な角度や強いトリミングは避けてください。

衣類/アイテム写真のガイドライン

1. 商品写真が最適です： 白またはニュートラルな背景の公式商品画像。
2. 明確な視認性： アイテムが主役であり、隠れていないこと。
3. 複数のアングル： 衣類では正面からの視点が最も重要です。
4. 色の正確さ： 写真が実際の色を示していることを確認してください（強いフィルターは不可）。
5. 高解像度： 詳細な商品画像ほど、より良い試着結果が得られます。

---

9. カスタム試着のためのプロンプトエンジニアリング

デフォルトのカテゴリプロンプトが期待どおりの結果を生成しない場合は、カスタム prompt を使用してください。次のガイドラインに従ってください：

5要素の試着プロンプト構造

[person preservation] + [item description] + [fit/positioning] + [style/mood] + [quality anchors]

主要な原則

1. 常に本人らしさを保つ： 「その人の顔、体型、ポーズをまったく同じに保つ。」
2. アイテムを明確に記述する： 「2枚目の画像の赤いレザージャケットを着用している」
3. フィット感と位置を指定する： 「自然なドレープ、適切な肩のフィット、リアルなしわ」
4. スタイルの文脈を加える： 「カジュアルなストリートスタイルのルック」「フォーマルなビジネスウェア」
5. 品質のアンカー： 「プロフェッショナルなファッション写真」「エディトリアル品質」「リアルな影」

カスタムプロンプトの例

フォーマルな服装：

The person is wearing the navy blue suit from the second image. Keep the person's face, body, and pose exactly the same. The suit should fit perfectly with proper tailoring — clean shoulder line, correct sleeve length, natural lapel lay. Professional fashion photography quality with studio lighting.

カジュアルなストリートスタイル：

The person is wearing the oversized hoodie from the second image in a relaxed street style. Keep the person's identity and pose the same. The hoodie should drape naturally with realistic fabric weight and casual fit. Urban photography style.

ジュエリーの組み合わせ：

The person is wearing the diamond pendant necklace from the second image. Keep everything about the person the same. The necklace should sit naturally on the collarbone with realistic sparkle and light reflections. The chain length and pendant size should be proportional to the person's frame.

---

10. エラー処理

エラー	原因	解決策
「Person image error: Either person_path or person_url must be provided」	人物写真が不足しています	ユーザーに写真を求めます
「Garment/item image error: Either garment_path or garment_url must be provided」	アイテム写真が不足しています	ユーザーにアイテムの写真を求めます
「File not found」	無効なファイルパス	ファイルパスを確認して再試行します
「Unsupported image format」	画像以外のファイル	JPG、PNG、または WebP を使用してください
「Image too large」	ファイルが 10 MB 超	画像をリサイズまたは圧縮してください
「Unknown category」	無効なカテゴリキー	有効な8つのカテゴリのいずれかを使用してください
低品質な結果	入力写真の品質が低い	より高解像度で、十分な明るさの写真を使用してください
アイテムの配置が誤っている	体の位置が不明確	対象領域が見える正面を向いた写真を使用してください

---

11. このスキルを使用しない場合

• 単一画像の編集（衣類/アイテムの参照なし）→ image-edit スキルを使用してください
• ポートレート生成（1つの参照からスタイル化された写真）→ image-portrait スキルを使用してください
• テキストから画像（参照写真がまったくない）→ image-create スキルを使用してください
• ファッションモデル生成（モデルをゼロから作成する）→ image-create スキルを使用してください