| name | image-edit |
| version | 1.0.5 |
| description | Image editing and enhancement of an existing image. Covers background replacement, super-resolution upscaling, old photo restoration, colorization, person removal, portrait retouching (skin smoothing, blemish removal), slimming, color grading, artistic filters, image blending, outpainting, local editing, text rendering, multi-angle generation, before/after comparison, car recoloring, car wrap preview.
Use when editing, enhancing, or transforming an existing image (e.g. remove background, upscale photo, restore old photo, retouch portrait, change car color, apply filter, extend image).
|
| metadata | {"starchild":{"emoji":"✏️","skillKey":"image-edit"}} |
| user-invocable | true |
| disable-model-invocation | false |
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",
)
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:
- Use each image's
local_path (e.g. output/images/xxx.png) — the script always downloads on success.
- Tell the user the files are saved to
output/images/ and viewable in the workspace file panel.
- On Web channel, embed inline so the user can preview in chat:
- 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:
- Default: always use
nanopro unless the user explicitly requests higher quality.
- 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).
- Use
nanopro when: user wants fast results, is iterating on edits, or the edit is straightforward.
result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg")
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",
)
Key principles (from reference skills)
-
Be specific about the change — vague prompts produce poor results:
- ❌ "make it better"
- ✅ "increase contrast, add warm golden tones, sharpen details"
-
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"
-
Specify materials and finishes — for car and product edits:
- ❌ "make it blue"
- ✅ "deep metallic blue with a glossy clear coat finish"
-
Reference real-world styles — for filters and artistic effects:
- ❌ "make it artistic"
- ✅ "apply a warm cinematic color grade like Wes Anderson films"
-
Describe the era for restoration/colorization:
- ❌ "colorize this"
- ✅ "colorize this 1940s family portrait with period-appropriate clothing colors"
-
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())
result = edit_image(
image_path="uploads/portrait.jpg",
prompt="a modern office with floor-to-ceiling windows and city skyline view",
action="replace_bg",
)
result = edit_image(
image_path="uploads/product.jpg",
prompt="clean white studio background with soft shadow",
action="replace_bg",
)
Old photo restoration
result = edit_image(
image_path="uploads/old_family_photo.jpg",
prompt="repair all scratches, tears, and stains; restore faded colors; enhance clarity",
action="restore",
)
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
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",
)
result = edit_image(
image_path="uploads/photo.jpg",
prompt="subtle facial slimming, slightly more defined jawline, natural proportions",
action="slim",
)
Image enhancement
result = edit_image(
image_path="uploads/landscape.jpg",
prompt="cinematic color grading with warm golden tones, enhanced contrast, vibrant but natural colors",
action="enhance",
)
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
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",
)
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
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
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
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):
FAL_KEY=your-fal-key python3 skills/image-edit/edit_image.py photo.jpg "make it brighter" enhance nanopro
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 |
