image-edit

Use this skill for all image editing and enhancement requests on Starchild.

Covers: general editing, background replacement, super-resolution, old photo restoration, colorization, person removal, portrait retouching (skin smoothing, blemish removal, teeth whitening), slimming, color grading, artistic filters, image blending, outpainting, local editing, text rendering, multi-angle generation, before/after comparison, car recoloring, car wrap preview, and fitness/medical transformation comparisons.

Core principle: call the provided script. Do not re-implement proxy/billing plumbing.

When to use image-edit vs other image skills:

• image-edit → user wants to EDIT, ENHANCE, or TRANSFORM an existing image
• image-portrait → user wants a portrait with their face/identity preserved from a reference photo
• image-create → user wants to CREATE something from a text description (no source image)

---

1. Quick start — basic edit (most common)

exec(open('skills/image-edit/edit_image.py').read())
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="make the sky more dramatic with golden sunset colors",
    action="enhance",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}

The script reads the local file, base64-encodes it, and sends it to fal.ai as a data URI — no manual URL publishing needed.

2. Quick start — public URL

exec(open('skills/image-edit/edit_image.py').read())
result = edit_image(
    image_url="https://example.com/photo.jpg",
    prompt="replace the background with a tropical beach",
    action="replace_bg",
)

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:

   ![edited](output/images/<filename>.png)

1. 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").

---

3. Parameters

*At least one of image_path or image_url must be provided. If both are given, image_path takes priority.

---

4. Actions — operation types

F: Multi-image / general editing

G: Professional editing

V: Retouching / beauty

W: Medical / fitness comparison

X: Automotive

---

5. 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 edit requires very precise detail preservation (e.g., complex text rendering, fine inpainting).
3. Use nanopro when: user wants fast results, is iterating on edits, or the edit is straightforward.

# Default (fast)
result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg")

# High quality (user requested)
result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg", model="gpt")

---

6. Intent recognition guide

Use this table to map user requests to the correct action:

General editing

Professional editing

Retouching / beauty

Medical / fitness

Automotive

---

7. Prompt engineering best practices

The prompt template system

Every action has a built-in prompt template that wraps the user's instruction for optimal results. You only need to pass the user's specific intent — the template adds the technical quality instructions automatically.

For example, if the user says "make the background a sunset beach":

result = edit_image(
    image_path="photo.jpg",
    prompt="a beautiful sunset beach with palm trees and golden light",
    action="replace_bg",
)
# The script wraps this into: "Replace the background of this image: a beautiful
# sunset beach with palm trees and golden light. Keep the foreground subject
# perfectly intact with clean edges. Match the lighting direction..."

Key principles (from reference skills)

1. Be specific about the change — vague prompts produce poor results:

• ❌ "make it better"
• ✅ "increase contrast, add warm golden tones, sharpen details"

1. Describe what to preserve — especially for local edits:

• ❌ "change the shirt"
• ✅ "change the shirt color to navy blue, keep the same fabric texture and wrinkles"

1. Specify materials and finishes — for car and product edits:

• ❌ "make it blue"
• ✅ "deep metallic blue with a glossy clear coat finish"

1. Reference real-world styles — for filters and artistic effects:

• ❌ "make it artistic"
• ✅ "apply a warm cinematic color grade like Wes Anderson films"

1. Describe the era for restoration/colorization:

• ❌ "colorize this"
• ✅ "colorize this 1940s family portrait with period-appropriate clothing colors"

1. For retouching, specify the level:

• Light: "subtle skin smoothing, keep natural texture"
• Medium: "professional retouching, remove blemishes, even skin tone"
• Heavy: "full beauty retouching, smooth skin, brighten eyes, whiten teeth"

---

8. Usage examples by scenario

Background replacement

exec(open('skills/image-edit/edit_image.py').read())

# Simple background swap
result = edit_image(
    image_path="uploads/portrait.jpg",
    prompt="a modern office with floor-to-ceiling windows and city skyline view",
    action="replace_bg",
)

# Studio background
result = edit_image(
    image_path="uploads/product.jpg",
    prompt="clean white studio background with soft shadow",
    action="replace_bg",
)

Old photo restoration

# Repair damaged photo
result = edit_image(
    image_path="uploads/old_family_photo.jpg",
    prompt="repair all scratches, tears, and stains; restore faded colors; enhance clarity",
    action="restore",
)

# Colorize black-and-white photo
result = edit_image(
    image_path="uploads/grandpa_1945.jpg",
    prompt="colorize with historically accurate colors for 1940s era, natural skin tones, period-appropriate clothing",
    action="colorize",
)

Portrait retouching

# Professional retouching
result = edit_image(
    image_path="uploads/selfie.jpg",
    prompt="professional portrait retouching: smooth skin while keeping natural texture, remove blemishes, subtle teeth whitening, brighten eyes",
    action="retouch",
)

# Slimming
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="subtle facial slimming, slightly more defined jawline, natural proportions",
    action="slim",
)

Image enhancement

# Color grading
result = edit_image(
    image_path="uploads/landscape.jpg",
    prompt="cinematic color grading with warm golden tones, enhanced contrast, vibrant but natural colors",
    action="enhance",
)

# Artistic filter
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="oil painting style with visible brushstrokes, rich warm palette, impressionist feel",
    action="filter",
)

Super-resolution upscaling

result = edit_image(
    image_path="uploads/low_res.jpg",
    prompt="upscale to maximum quality, enhance fine details, reduce noise and compression artifacts",
    action="upscale",
)

Person removal

result = edit_image(
    image_path="uploads/group_photo.jpg",
    prompt="remove the person on the far right, fill with the park background seamlessly",
    action="remove_person",
)

Outpainting (image extension)

result = edit_image(
    image_path="uploads/cropped.jpg",
    prompt="extend the image to the left and right, continuing the mountain landscape naturally",
    action="extend",
    aspect_ratio="16:9",
)

Car customization

# Car recolor
result = edit_image(
    image_path="uploads/my_car.jpg",
    prompt="change to a deep cherry red metallic paint with glossy clear coat",
    action="car_color",
)

# Car wrap preview
result = edit_image(
    image_path="uploads/my_car.jpg",
    prompt="matte black vinyl wrap with carbon fiber accents on the hood and mirrors",
    action="car_wrap",
)

Before/after comparison

# Fitness transformation
result = edit_image(
    image_path="uploads/fitness_photo.jpg",
    prompt="create a fitness transformation comparison showing a more toned and fit version",
    action="comparison",
)

Local editing

# Change specific element
result = edit_image(
    image_path="uploads/outfit.jpg",
    prompt="change only the dress color from red to emerald green, keep the same fabric texture",
    action="local_edit",
)

Text rendering

result = edit_image(
    image_path="uploads/poster_bg.jpg",
    prompt="add the text 'SUMMER SALE' in bold white letters centered at the top, with a subtle drop shadow",
    action="text_render",
)

High quality edit

# Use GPT model for best quality
result = edit_image(
    image_path="uploads/important_photo.jpg",
    prompt="professional color correction and enhancement for print publication",
    action="enhance",
    model="gpt",
)

---

9. Provided scripts

---

10. Local testing

Set FAL_KEY env var to call fal.ai directly (bypasses sc-proxy):

# Basic edit
FAL_KEY=your-fal-key python3 skills/image-edit/edit_image.py photo.jpg "make it brighter" enhance nanopro

# Args: <image_path_or_url> [prompt] [action] [model]

---

11. Troubleshooting

---

12. Infrastructure (reference)

• Caller → sc-proxy → queue.fal.run/{model} → fal model providers
• All requests must include Authorization: Key fake-falai-key-12345 (proxy injects the real FAL_KEY)
• Pre-charge happens at submit. Poll/result calls are free.
• Local files are base64-encoded as data URIs — no separate upload step needed.
• Final images live at https://*.fal.media/... — public CDN, no auth needed for download.
• Cost tracking via _cost_track.py — records X-Credits-Used from sc-proxy response headers.

Model endpoints

---