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)

⚠️ 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-edit")
from exports import edit_image
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="make the sky more dramatic with golden sunset colors",
    action="enhance",
)
print(result)
EOF

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

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)
   

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

---

3. Parameters

Parameter	Required	Default	Description
image_path	yes*	—	Local workspace file path to the source image
image_url	yes*	—	Public HTTPS URL of the source image
prompt	no	auto	Editing instruction (what to change)
action	no	"edit"	Operation type (see §4)
model	no	"nanopro"	Model: "nanopro" (fast ~25s) or "gpt" (best quality ~150s)
aspect_ratio	no	None	Output ratio: 1:1, 3:4, 4:3, 9:16, 16:9. None = preserve original.

*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

Action	Key	Description
General edit	edit	Modify the image according to the prompt
Image blending	blend	Place a person/subject into a new background or scene
Outpainting	extend	Extend the image beyond its current boundaries
Local edit	local_edit	Modify only a specific region of the image
Structural redesign	restructure	Change layout/grid/column count or rearrange elements — overrides "preserve composition"
Text rendering	text_render	Add or modify text within the image
Multi-angle	multi_angle	Generate different viewing angles from one photo
Before/after	before_after	Generate a side-by-side comparison image

G: Professional editing

Action	Key	Description
Background replacement	replace_bg	Swap the background while keeping the subject
Super-resolution	upscale	Upscale and enhance image resolution
Photo restoration	restore	Repair scratches, tears, fading in old photos
Colorization	colorize	Add realistic colors to black-and-white photos
Person removal	remove_person	Remove a specific person from the photo

V: Retouching / beauty

Action	Key	Description
Portrait retouching	retouch	Skin smoothing, blemish removal, teeth whitening
Slimming	slim	Adjust facial and body proportions subtly
Enhancement	enhance	Color correction, lighting improvement, quality boost
Artistic filter	filter	Apply a specific artistic style or filter effect

W: Medical / fitness comparison

Action	Key	Description
Transformation comparison	comparison	Before/after for medical, fitness, or transformation

X: Automotive

Action	Key	Description
Car recolor	car_color	Change the color of a vehicle
Car wrap preview	car_wrap	Visualize a wrap or film on a vehicle

---

5. Model selection guide

Model	Key	Speed	Quality	Best for
NanoPro	nanopro	~25s	Good	Default for all requests. Fast iteration.
GPT Image 2	gpt	~150s	Best	When user explicitly asks for "highest quality" or "best quality". Complex edits.

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

User says	Action	Prompt hint
"edit this photo", "modify this image"	edit	Pass user's instruction as prompt
"put me on a beach", "change the scene"	blend	Describe the target scene
"extend the image", "make it wider", "outpaint"	extend	Describe what to add
"change just the shirt color", "edit only the sky"	local_edit	Specify the region and change
"fewer columns", "simplify the grid", "rearrange the layout", "make it 7 columns max"	restructure	State the target structure explicitly (rows/columns/arrangement)
"add text", "write 'Hello' on the image"	text_render	Specify text content and placement
"show from the side", "different angle"	multi_angle	Describe the desired angle
"before and after", "show the difference"	before_after	Describe the transformation

Professional editing

User says	Action	Prompt hint
"remove background", "change background", "换背景"	replace_bg	Describe the new background
"upscale", "make it higher resolution", "enhance quality"	upscale	Optionally specify target quality
"restore old photo", "fix this damaged photo", "修复老照片"	restore	Describe specific damage to fix
"colorize", "add color to B&W photo", "上色"	colorize	Optionally describe expected colors
"remove this person", "P掉某人"	remove_person	Describe which person to remove

Retouching / beauty

User says	Action	Prompt hint
"retouch", "smooth skin", "remove blemishes", "磨皮美白"	retouch	Specify retouching level
"make me thinner", "slim face", "瘦脸"	slim	Specify areas to adjust
"enhance colors", "improve lighting", "调色"	enhance	Describe desired look
"apply filter", "make it look vintage", "滤镜"	filter	Describe the filter style

Medical / fitness

User says	Action	Prompt hint
"before and after surgery", "fitness transformation"	comparison	Describe the transformation context

Automotive

User says	Action	Prompt hint
"change car color", "make it red", "汽车改色"	car_color	Specify the target color and finish
"car wrap", "vinyl wrap preview", "贴膜预览"	car_wrap	Describe wrap material and color

---

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"

2. 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"

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

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

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

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

5. Describe the era for restoration/colorization:

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

6. 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

File	Purpose
edit_image.py	Core script: resolve image → build prompt → submit → poll → download. Handles local files (base64) and URLs, all actions, two models.
exports.py	Re-exports edit_image, ACTIONS, ACTION_PROMPTS, MODELS for programmatic use by other skills.
_cost_track.py	Cost tracking helper — records per-call costs via sc-proxy headers.

---

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

Problem	Fix
File not found: ...	Check the workspace path; the file must exist
Unsupported image format	Use .jpg, .jpeg, .png, .webp, or .bmp
Image too large	Resize to under 10 MB before uploading
image_url must be a public HTTP(S) URL	Use image_path for local files, or provide a valid https:// URL
Unknown action	Check valid actions in §4
HTTP 402 insufficient_credits	Top up balance; cost is pre-charged on submit
HTTP 403 endpoint_not_allowed	sc-proxy only allows approved fal endpoints; contact admin
Edit FAILED upstream	Simplify prompt, ensure source image is clear, retry
Job stuck IN_PROGRESS >10 min	Save request_id, retry later
Poor edit quality	Try model="gpt" for higher quality; be more specific in prompt
Layout/grid/column count won't change no matter how many times you iterate	Prefer action="restructure" for structural changes — its template mandates the layout change. Plain edit now has a precedence fallback (explicit structural instructions override composition preservation), but treat it only as a compatibility net, not the primary path
Background not fully removed	Use replace_bg action with explicit background description
Retouching looks unnatural	Add "keep natural texture" or "subtle" to prompt

---

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

Model	Edit endpoint
nanopro	fal-ai/nano-banana-pro/edit
gpt	openai/gpt-image-2/edit

---