image-tryon

image-tryon

在 Starchild 上处理所有虚拟试穿请求时，请使用此技能。

涵盖：服装试穿、配饰试戴、发型预览、妆容预览、眼镜试戴、帽子试戴、鞋子试穿、手表试戴。

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

与 image-edit 的主要区别：试穿始终需要两张图片——一张人物照片和一张服装／物品照片。

---

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

heredoc（<<'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，则优先使用路径。
• 两张图片都是必需的 —— 试穿无法仅凭一张图片完成。

提示词优先级：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. 照片要求——最佳实践

人物照片指南

类别	推荐的照片类型	提示
服装	正面全身照	双臂稍微离开身体，姿势自然
配饰	相关身体部位清晰可见	配饰佩戴部位光线充足
发型	清晰的头部／面部照，正面或 3/4 侧面	将头发向后梳，或确保当前发型清晰可见
妆容	正面面部特写	面部干净、光线均匀充足、没有浓妆
眼镜	面部正对镜头，眼睛清晰可见	不戴现有眼镜，眼部区域清晰
帽子	正面头肩照	不戴现有帽子，头发清晰可见
鞋子	全身照或腿脚清晰可见	站立姿势，当前鞋子清晰可见
手表	手腕／前臂清晰可见	手腕未佩戴饰品，或当前手表清晰可见

一般照片质量规则

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. 清楚描述物品： “穿着第二张图片中的红色皮夹克”
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 技能
• 人像生成（根据单张参考图生成风格化照片）→ 使用 image-portrait 技能
• 文生图（完全没有参考照片）→ 使用 image-create 技能
• 时尚模特生成（从零开始创建模特）→ 使用 image-create 技能