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.

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

⚠️ Execution context — read this first. The code blocks below are Python, not shell commands. Starchild's bash tool runs /bin/bash -c, which cannot parse exec(open(...)) — pasting them directly into a bash command will fail with syntax error near unexpected token 'open'. Also, exec(open(...)) inside python3 -c fails with NameError: __file__ because the script uses __file__ for path resolution.

Use python3 - <<'EOF' with from exports import when calling via the bash tool:

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

The heredoc (<<'EOF') preserves all quotes and newlines — no escaping needed.

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

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

2. Quick start — URL inputs

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

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:

   ![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").

4. Parameters

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.

5. Try-on categories

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

Category details

6. Model selection guide

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.

# 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. Usage examples by category

Clothing try-on

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

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

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

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

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

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

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

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)

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

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. Photo requirements — best practices

Person photo guidelines

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.

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.

9. Prompt engineering for custom try-on

When the default category prompt doesn't produce the desired result, use a custom prompt. Follow these guidelines:

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"

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

11. When NOT to use this skill

• 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