image-edit

image-edit

在 Starchild 上处理所有图像编辑和增强请求时使用此技能。

涵盖：常规编辑、替换背景、超分辨率、老照片修复、上色、移除人物、人像修饰（平滑肌肤、去除瑕疵、美白牙齿）、瘦身、调色、艺术滤镜、图像融合、扩展画布、局部编辑、文字渲染、多角度生成、编辑前后对比、汽车改色、汽车贴膜预览，以及健身／医疗效果对比。

**核心原则：**调用提供的脚本。不要重新实现代理／计费流程。

何时使用 image-edit，而非其他图像技能：

• image-edit → 用户想要编辑、增强或转换现有图像
• image-portrait → 用户想要生成一张保留其参考照片中面部／身份特征的人像
• image-create → 用户想根据文字描述创作内容（无源图像）

---

1. 快速开始——基础编辑（最常见）

⚠️ 执行环境——请先阅读。 以下代码块是 Python，不是 shell 命令。Starchild 的 bash 工具 运行 /bin/bash -c，无法解析 exec(open(...))——直接将其粘贴到 bash 命令中 会因 syntax error near unexpected token 'open' 而失败。 此外，在 python3 -c 中使用 exec(open(...)) 会因脚本使用 __file__ 解析路径而失败，并报错 NameError: __file__。

通过 bash 工具调用时，请使用 python3 - <<'EOF' 和 from exports import：

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

heredoc（<<'EOF'）会保留所有引号和换行，无需转义。

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

脚本会读取本地文件，将其编码为 base64，然后作为数据 URI 发送到 fal.ai——无需手动发布 URL。

2. 快速开始——公共 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",
)

向用户交付结果——重要

切勿将 fal.media 原始 URL 直接交给用户。 fal 提供的文件带有限制性 CSP 标头。唯一可靠的交付方式是使用已下载到本地的文件：

1. 使用每张图像的 local_path（例如 output/images/xxx.png）——脚本在成功后总会下载文件。
2. 告知用户文件已保存到 output/images/，可在工作区文件面板中查看。
3. 在 Web 渠道中，将图像内嵌显示，以便用户在聊天中预览：

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

4. 在 Telegram／WeChat 中，通过 send_to_telegram(file_path="output/images/...", message_type="image") 或 send_to_wechat(file_path="output/images/...", message_type="image") 发送。

---

3. 参数

参数	必填	默认值	说明
image_path	是*	—	源图像在本地工作区中的文件路径
image_url	是*	—	源图像的公共 HTTPS URL
prompt	否	自动	编辑指令（要进行的更改）
action	否	"edit"	操作类型（参见 §4）
model	否	"nanopro"	模型："nanopro"（快速，约 25 秒）或 "gpt"（质量最佳，约 150 秒）
aspect_ratio	否	None	输出宽高比：1:1、3:4、4:3、9:16、16:9。None = 保留原图比例。

*必须提供 image_path 或 image_url 中的至少一个。如果两者都提供，则优先使用 image_path。

---

4. 操作——操作类型

F：多图 / 通用编辑

操作	键	描述
通用编辑	edit	根据提示词修改图像
图像融合	blend	将人物 / 主体置于新的背景或场景中
扩展画布	extend	将图像扩展至当前边界之外
局部编辑	local_edit	仅修改图像的特定区域
结构重设计	restructure	更改布局 / 网格 / 列数或重新排列元素 — 覆盖“保留构图”的要求
文本渲染	text_render	在图像中添加或修改文本
多角度	multi_angle	根据一张照片生成不同视角的图像
前后对比	before_after	生成并排对比图像

G：专业编辑

操作	键	描述
替换背景	replace_bg	替换背景，同时保留主体
超分辨率	upscale	提高并增强图像分辨率
照片修复	restore	修复旧照片上的划痕、撕裂和褪色
黑白照片上色	colorize	为黑白照片添加逼真的色彩
移除人物	remove_person	从照片中移除特定人物

V：修饰 / 美化

操作	键	描述
肖像修饰	retouch	磨皮、去除瑕疵、美白牙齿
瘦身	slim	微调面部和身体比例
增强	enhance	校正色彩、改善光照、提升画质
艺术滤镜	filter	应用特定的艺术风格或滤镜效果

W：医疗 / 健身对比

操作	键	描述
转变对比	comparison	用于医疗、健身或形象转变的前后对比

X：汽车

操作	键	描述
汽车改色	car_color	更改车辆颜色
汽车贴膜预览	car_wrap	预览车辆贴膜或车身膜效果

---

5. 模型选择指南

模型	键	速度	质量	最适合
NanoPro	nanopro	~25s	良好	所有请求的默认选择。快速迭代。
GPT Image 2	gpt	~150s	最佳	用户明确要求“最高质量”或“最佳质量”时。复杂编辑。

决策规则：

1. **默认：**除非用户明确要求更高质量，否则始终使用 nanopro。
2. **使用 gpt 的情况：**用户说“最高质量”“最佳质量”“高级”，或编辑需要非常精确地保留细节（例如，复杂的文本渲染、精细的局部重绘）。
3. **使用 nanopro 的情况：**用户希望快速获得结果、正在迭代修改，或编辑任务较为简单。

# 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. 意图识别指南

使用此表将用户请求映射到正确的操作：

通用编辑

用户说	操作	提示词提示
“编辑这张照片”“修改这张图像”	edit	将用户的指示作为提示词传入
“把我放到海滩上”“更换场景”	blend	描述目标场景
“扩展图像”“把它加宽”“扩展画布”	extend	描述要添加的内容
“只更改衬衫颜色”“只编辑天空”	local_edit	指定区域和要进行的更改
“减少列数”“简化网格”“重新排列布局”“最多 7 列”	restructure	明确说明目标结构（行 / 列 / 排列方式）
“添加文字”“在图像上写‘Hello’”	text_render	指定文本内容和位置
“从侧面展示”“换个角度”	multi_angle	描述所需的角度
“前后对比”“展示差异”	before_after	描述转变效果

专业编辑

用户说	操作	提示词提示
"remove background", "change background", "换背景"	replace_bg	描述新背景
"upscale", "make it higher resolution", "enhance quality"	upscale	可选指定目标质量
"restore old photo", "fix this damaged photo", "修复老照片"	restore	描述需要修复的具体损坏
"colorize", "add color to B&W photo", "上色"	colorize	可选描述预期颜色
"remove this person", "P掉某人"	remove_person	描述要移除的人

修图 / 美颜

用户说	操作	提示词提示
"retouch", "smooth skin", "remove blemishes", "磨皮美白"	retouch	指定修图程度
"make me thinner", "slim face", "瘦脸"	slim	指定需要调整的部位
"enhance colors", "improve lighting", "调色"	enhance	描述期望的效果
"apply filter", "make it look vintage", "滤镜"	filter	描述滤镜风格

医疗 / 健身

用户说	操作	提示词提示
"before and after surgery", "fitness transformation"	comparison	描述变化背景

汽车

用户说	操作	提示词提示
"change car color", "make it red", "汽车改色"	car_color	指定目标颜色和表面效果
"car wrap", "vinyl wrap preview", "贴膜预览"	car_wrap	描述贴膜材质和颜色

---

7. 提示词工程最佳实践

提示词模板系统

每项操作都内置了提示词模板，会对用户指令进行包装，以获得最佳效果。你只需传入用户的具体意图，模板会自动添加技术质量要求。

例如，用户说“把背景换成日落海滩”：

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

关键原则（摘自参考技能）

1. 明确描述要做的修改——模糊的提示词会导致效果不佳：

   • ❌ “让它更好看”
   • ✅ “提高对比度，添加温暖的金色调，锐化细节”

2. 说明需要保留的内容——局部编辑时尤其重要：

   • ❌ “换件衬衫”
   • ✅ “将衬衫颜色改为海军蓝，保留相同的面料纹理和褶皱”

3. 指定材质和表面效果——适用于汽车和产品编辑：

   • ❌ “改成蓝色”
   • ✅ “深金属蓝，带亮面透明涂层效果”

4. 参考真实世界的风格——适用于滤镜和艺术效果：

   • ❌ “让它更有艺术感”
   • ✅ “应用类似 Wes Anderson 电影的温暖电影色调”

5. 修复 / 上色时描述时代背景：

   • ❌ “给这张照片上色”
   • ✅ “为这张 1940 年代的家庭肖像上色，采用符合当时风格的服装颜色”

6. 修图时指定程度：

   • 轻度：“轻微磨皮，保留自然纹理”
   • 中度：“专业修图，去除瑕疵，均匀肤色”
   • 重度：“全面美颜修图，磨皮，提亮眼睛，美白牙齿”

---

8. 按场景划分的使用示例

替换背景

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

修复老照片

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

人像修图

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

图像增强

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

超分辨率放大

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

移除人物

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

扩图（扩展图像）

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

前后对比

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

局部编辑

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

文本渲染

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

高质量编辑

# 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. 提供的脚本

文件	用途
edit_image.py	核心脚本：解析图像 → 构建提示词 → 提交 → 轮询 → 下载。支持本地文件（base64）和 URL、所有操作及两种模型。
exports.py	重新导出 edit_image、ACTIONS、ACTION_PROMPTS、MODELS，供其他技能以编程方式使用。
_cost_track.py	费用跟踪辅助工具——通过 sc-proxy 响应头记录每次调用的费用。

---

10. 本地测试

设置 FAL_KEY 环境变量，直接调用 fal.ai（绕过 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. 故障排查

问题	解决方法
File not found: ...	检查工作区路径；文件必须存在
Unsupported image format	请使用 .jpg、.jpeg、.png、.webp 或 .bmp
Image too large	上传前将图片缩小到 10 MB 以下
image_url must be a public HTTP(S) URL	本地文件请使用 image_path，或提供有效的 https:// URL
Unknown action	请查看 §4 中的有效操作
HTTP 402 insufficient_credits	充值；提交时会预先扣费
HTTP 403 endpoint_not_allowed	sc-proxy 仅允许使用已批准的 fal 端点；请联系管理员
编辑上游返回 FAILED	简化提示词，确保源图片清晰，然后重试
任务 IN_PROGRESS 状态持续超过 10 分钟	保存 request_id，稍后重试
编辑质量较差	尝试使用 model="gpt" 以获得更高质量；在提示词中提供更具体的描述
无论迭代多少次，布局／网格／列数都无法更改	结构调整优先使用 action="restructure"——其模板强制要求更改布局。普通 edit 现在有优先级回退机制（明确的结构指令会覆盖保留构图的要求），但请仅将其视为兼容性兜底，而非首选方案
背景未完全移除	使用 replace_bg 操作，并明确描述背景
修饰效果看起来不自然	在提示词中添加“保持自然纹理”或“微妙”

---

12. 基础设施（参考）

• 调用方 → sc-proxy → queue.fal.run/{model} → fal 模型提供方
• 所有请求都必须包含 Authorization: Key fake-falai-key-12345（代理会注入真实的 FAL_KEY）
• 提交时会预先扣费。轮询／获取结果的调用免费。
• 本地文件会被编码为 base64 数据 URI——无需单独上传。
• 最终图片位于 https://*.fal.media/...——这是公共 CDN，下载无需身份验证。
• 通过 _cost_track.py 跟踪费用——该脚本会记录 sc-proxy 响应头中的 X-Credits-Used。

模型端点

模型	编辑端点
nanopro	fal-ai/nano-banana-pro/edit
gpt	openai/gpt-image-2/edit

---