Back to Details

image-tryon

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

image-tryon

image-tryon

Use this skill for all virtual try-on requests on Starchild.
Covers: clothing try-on, accessory try-on, hairstyle preview, makeup preview, glasses try-on, hat try-on, shoes try-on, watch try-on.
Core principle: call the provided script. Do not re-implement proxy/billing plumbing.
Key difference from image-edit: try-on always requires two images — a person photo and a garment/item photo.
在Starchild上处理所有虚拟试穿请求时使用此技能。
涵盖：服装试穿、配饰试穿、发型预览、妆容预览、眼镜试穿、帽子试穿、鞋子试穿、手表试穿。
核心原则： 调用提供的脚本。请勿重新实现代理/计费相关的底层逻辑。
与image-edit的关键区别： 试穿始终需要两张图片——人物照片和服饰/物品照片。

1. Quick start — clothing try-on (most common)

1. 快速入门——服装试穿（最常见场景）

python
exec(open('skills/image-tryon/try_on.py').read())
result = try_on(
    person_path="uploads/person.jpg",
    garment_path="uploads/dress.jpg",
    category="clothing",
)
python
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/..."}], ...}

result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}


The script reads both local files, base64-encodes them, and sends them to fal.ai as data URIs — no manual URL publishing needed.

该脚本会读取两个本地文件，将其进行base64编码，并以数据URI的形式发送至fal.ai——无需手动发布URL。

2. Quick start — URL inputs

2. 快速入门——URL输入

python
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",
)
python
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. Quick start — glasses try-on

3. 快速入门——眼镜试穿

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

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:
  1. Use each image's 
    local_path
    (e.g. 
    output/images/xxx.png
    ) — the script always downloads on success.
  2. Tell the user the files are saved to 
    output/images/
    and viewable in the workspace file panel.
  3. On Web channel, embed inline so the user can preview in chat:
    markdown
    ![try-on result](output/images/<filename>.png)
  4. 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")
    .
绝不能直接将原始fal.media URL交给用户。 fal提供的文件带有严格的CSP头部限制。唯一可靠的交付方式是使用已下载的本地文件：
  1. 使用每张图片的
    local_path
    （例如
    output/images/xxx.png
    ）——脚本在执行成功后总会自动下载文件。
  2. 告知用户文件已保存至
    output/images/
    ，可在工作区文件面板中查看。
  3. 在Web渠道中，可将图片内嵌到聊天中供用户预览：
    markdown
    ![试穿结果](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")
    发送图片。

4. Parameters

4. 参数说明

ParameterRequiredDefaultDescription
person_path
yes*—Local workspace file path to the person's photo
person_url
yes*—Public HTTPS URL of the person's photo
garment_path
yes*—Local workspace file path to the garment/item photo
garment_url
yes*—Public HTTPS URL of the garment/item photo
category
no
"clothing"
Try-on category key (see §5)
prompt
no
None
Custom prompt — overrides category default when set
model
no
"nanopro"
Model: 
"nanopro"
(fast ~25s) or 
"gpt"
(best quality ~150s)
aspect_ratio
no
"3:4"
Output ratio: 
1:1
, 
3:4
, 
4:3
, 
9:16
, 
16:9
Image input rules:
  • Person image: provide 
    person_path
    OR 
    person_url
    (one is required).
  • Garment/item image: provide 
    garment_path
    OR 
    garment_url
    (one is required).
  • If both path and URL are given for the same image, path takes priority.
  • Both images are required — try-on cannot work with only one image.
Prompt priority: 
prompt
(full override) > 
category
default prompt.
参数是否必填默认值描述
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
（完全覆盖） > 类别默认提示词。

5. Try-on categories

5. 试穿类别

Intent recognition — what the user says → which category to use

意图识别——用户表述对应类别

User saysCategoryKey
"try on this dress/shirt/jacket/outfit"Clothing
clothing
"put this necklace/scarf/bag on me"Accessory
accessory
"show me with this hairstyle/hair color"Hairstyle
hairstyle
"apply this makeup/lipstick look"Makeup
makeup
"try on these glasses/sunglasses"Glasses
glasses
"put this hat/cap/beanie on me"Hat
hat
"try on these shoes/sneakers/boots"Shoes
shoes
"put this watch on my wrist"Watch
watch
用户表述类别标识
"试穿这条裙子/衬衫/夹克/这套衣服"服装
clothing
"给我戴上这条项链/围巾/这个包"配饰
accessory
"展示我留这个发型/染这个发色的样子"发型
hairstyle
"帮我化这个妆容/涂这款口红"妆容
makeup
"试戴这副眼镜/墨镜"眼镜
glasses
"给我戴上这顶帽子/棒球帽/针织帽"帽子
hat
"试穿这双鞋/运动鞋/靴子"鞋子
shoes
"给我戴上这块手表"手表
watch

Category details

类别详情

CategoryKeyBest forPhoto requirements
Clothing
clothing
Shirts, dresses, jackets, pants, coats, full outfitsFull body or upper body person photo
Accessory
accessory
Scarves, bags, belts, jewelry, necklaces, earringsRelevant body area visible
Hairstyle
hairstyle
Haircuts, hair colors, styling changesClear face/head photo
Makeup
makeup
Lipstick, eyeshadow, foundation, blush, full looksClear face close-up
Glasses
glasses
Prescription glasses, sunglasses, reading glassesClear face photo, front-facing
Hat
hat
Caps, beanies, fedoras, sun hats, helmetsHead and shoulders visible
Shoes
shoes
Sneakers, heels, boots, sandals, loafersFull body or lower body photo
Watch
watch
Analog, smartwatches, luxury watchesWrist/arm visible
类别标识适用场景照片要求
服装
clothing
衬衫、连衣裙、夹克、裤子、大衣、整套穿搭全身或上半身人物照片
配饰
accessory
围巾、包、腰带、珠宝、项链、耳环需露出相关身体部位
发型
hairstyle
发型、发色、造型变化清晰的面部/头部照片
妆容
makeup
口红、眼影、粉底、腮红、完整妆容清晰的面部特写
眼镜
glasses
近视眼镜、墨镜、老花镜清晰的正面面部照片
帽子
hat
棒球帽、针织帽、礼帽、遮阳帽、头盔需露出头部和肩膀
鞋子
shoes
运动鞋、高跟鞋、靴子、凉鞋、乐福鞋全身或下半身照片
手表
watch
机械表、智能手表、奢侈品手表需露出手腕/手臂

6. Model selection guide

6. 模型选择指南

ModelKeySpeedQualityBest for
NanoPro
nanopro
~25sGoodDefault for all requests. Fast iteration.
GPT Image 2
gpt
~150sBestWhen user explicitly asks for "highest quality" or "best quality".
Decision rules:
  1. Default: always use 
    nanopro
    unless the user explicitly requests higher quality.
  2. Use 
    gpt
    when:     user says "highest quality", "best quality", "premium", or the result needs to be photorealistic for professional use.
  3. Use 
    nanopro
    when:     user wants fast results, is trying multiple items, or iterating on looks.
python
undefined
模型标识速度质量适用场景
NanoPro
nanopro
~25秒良好所有请求的默认选项，适合快速迭代。
GPT Image 2
gpt
~150秒最佳当用户明确要求“最高质量”或“最佳效果”时使用。
决策规则：
  1. 默认设置： 除非用户明确要求更高质量，否则始终使用
    nanopro
    。
  2. 使用
    gpt
    的场景：     用户提及“最高质量”、“最佳效果”、“ premium”，或结果需要达到专业级照片真实度时。
  3. 使用
    nanopro
    的场景：     用户需要快速结果、尝试多款物品，或迭代不同造型时。
python
undefined

Default (fast)

默认（快速）

result = try_on(person_path="me.jpg", garment_path="dress.jpg", category="clothing")
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")

---
result = try_on(person_path="me.jpg", garment_path="dress.jpg", category="clothing", model="gpt")

---

7. Usage examples by category

7. 分场景使用示例

Clothing try-on

服装试穿

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

Accessory try-on

配饰试穿

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

Hairstyle preview

发型预览

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

Makeup preview

妆容预览

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

Glasses try-on

眼镜试穿

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

Hat try-on

帽子试穿

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

Shoes try-on

鞋子试穿

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

Watch try-on

手表试穿

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

Custom prompt (override default)

自定义提示词（覆盖默认）

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

Different aspect ratio

自定义比例

python
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
)
python
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",  # 全身竖版
)

8. Photo requirements — best practices

8. 照片要求——最佳实践

Person photo guidelines

人物照片指南

CategoryRecommended photo typeTips
ClothingFull body, front-facingArms slightly away from body, neutral pose
AccessoryRelevant body area visibleGood lighting on the area where accessory goes
HairstyleClear head/face, front or 3/4 viewHair pulled back or current style clearly visible
MakeupFace close-up, front-facingClean face, good even lighting, no heavy makeup
GlassesFace front-facing, eyes visibleNo existing glasses, clear eye area
HatHead and shoulders, front-facingNo existing hat, hair visible
ShoesFull body or legs/feet visibleStanding pose, current shoes visible
WatchWrist/forearm visibleBare wrist or current watch visible
类别推荐照片类型小贴士
服装全身正面照手臂略离身体，姿势自然
配饰露出相关身体部位配饰佩戴区域光线良好
发型清晰的头部/面部照片，正面或3/4侧面头发向后梳或当前发型清晰可见
妆容面部特写正面照面部干净，光线均匀，无浓妆
眼镜正面面部照，眼睛清晰可见未佩戴眼镜，眼部区域无遮挡
帽子头部和肩膀正面照未佩戴帽子，头发可见
鞋子全身或腿脚照片站立姿势，当前鞋子可见
手表手腕/小臂照片手腕裸露或当前手表可见

General photo quality rules

通用照片质量规则

  1. Lighting: well-lit, even lighting works best. Avoid harsh shadows on the face/body.
  2. Resolution: 1024×1024 or higher recommended. Low-res photos produce poor results.
  3. Angle: front-facing photos work best for most categories.
  4. Background: any background works, but clean backgrounds produce cleaner results.
  5. Pose: natural, relaxed poses. Avoid extreme angles or heavy cropping.
  1. 光线： 光线充足、均匀的照片效果最佳。避免面部/身体出现强烈阴影。
  2. 分辨率： 推荐1024×1024或更高分辨率。低分辨率照片会导致效果不佳。
  3. 角度： 正面照片适合大多数类别。
  4. 背景： 任何背景均可，但干净背景会产生更清晰的结果。
  5. 姿势： 自然放松的姿势。避免极端角度或过度裁剪。

Garment/item photo guidelines

服饰/物品照片指南

  1. Product shots work best: official product images on white/neutral backgrounds.
  2. Clear visibility: the item should be the main focus, not obscured.
  3. Multiple angles: front view is most important for clothing.
  4. Color accuracy: ensure the photo shows true colors (no heavy filters).
  5. High resolution: detailed product images produce better try-on results.
  1. 产品图效果最佳： 白色/中性背景的官方产品图。
  2. 清晰可见： 物品需为画面主体，无遮挡。
  3. 多角度： 服装类优先提供正面视图。
  4. 颜色准确： 照片需呈现物品真实颜色（无过重滤镜）。
  5. 高分辨率： 细节丰富的产品图会带来更好的试穿效果。

9. Prompt engineering for custom try-on

9. 自定义试穿的提示词工程

When the default category prompt doesn't produce the desired result, use a custom 
prompt
. Follow these guidelines:
当默认类别提示词无法产生理想结果时，可使用自定义
prompt
。请遵循以下指南：

The 5-element try-on prompt structure

试穿提示词五要素结构

[person preservation] + [item description] + [fit/positioning] + [style/mood] + [quality anchors]
[人物身份保留] + [物品描述] + [贴合度/位置] + [风格/氛围] + [质量锚点]

Key principles

核心原则

  1. Always preserve identity: "Keep the person's face, body shape, and pose exactly the same."
  2. Describe the item clearly: "wearing the red leather jacket from the second image"
  3. Specify fit and positioning: "natural draping, proper shoulder fit, realistic wrinkles"
  4. Add style context: "casual street style look", "formal business attire"
  5. Quality anchors: "professional fashion photography", "editorial quality", "realistic shadows"
  1. 始终保留身份： “保持人物的面部、体型和姿势完全不变。”
  2. 清晰描述物品： “穿着第二张图片中的红色皮夹克”
  3. 指定贴合度和位置： “自然垂坠，肩部贴合合身，褶皱真实”
  4. 添加风格背景： “休闲街头风格”、“正式商务着装”
  5. 质量锚点： “专业时尚摄影”、“杂志级画质”、“真实阴影”

Example custom prompts

自定义提示词示例

Formal outfit:
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.
Casual street style:
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.
Jewelry combination:
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. Error handling

10. 错误处理

ErrorCauseSolution
"Person image error: Either person_path or person_url must be provided"Missing person photoAsk user for their photo
"Garment/item image error: Either garment_path or garment_url must be provided"Missing item photoAsk user for the item photo
"File not found"Invalid file pathCheck the file path and try again
"Unsupported image format"Non-image fileUse JPG, PNG, or WebP
"Image too large"File > 10 MBResize or compress the image
"Unknown category"Invalid category keyUse one of the 8 valid categories
Low quality resultPoor input photosUse higher resolution, well-lit photos
Wrong item placementUnclear body positioningUse front-facing photos with target area visible
错误信息原因解决方案
"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"文件大小超过10MB调整图片尺寸或压缩文件
"Unknown category"类别标识无效使用8个有效类别之一
结果质量差输入照片质量不佳使用更高分辨率、光线良好的照片
物品位置错误身体姿势不清晰使用正面照片并确保目标区域可见

11. When NOT to use this skill

11. 不适用场景

  • Single image editing (no garment/item reference) → use 
    image-edit
    skill
  • Portrait generation (styled photos from one reference) → use 
    image-portrait
    skill
  • Text-to-image (no reference photos at all) → use 
    image-create
    skill
  • Fashion model generation (creating models from scratch) → use 
    image-create
    skill
  • 单张图片编辑（无服饰/物品参考）→ 使用
    image-edit
    技能
  • 肖像生成（基于单张参考图生成风格化照片）→ 使用
    image-portrait
    技能
  • 文本生成图片（无参考照片）→ 使用
    image-create
    技能
  • 时尚模特生成（从零创建模特）→ 使用
    image-create
    技能