image-edit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

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

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

**核心原则：**调用提供的脚本，不要重新实现代理/计费相关逻辑。

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

image-edit → 用户希望对现有图像进行编辑、增强或转换
image-portrait → 用户希望基于参考照片生成保留自身面部/身份的人像
image-create → 用户希望根据文字描述生成新内容（无源图像）

1. Quick start — basic edit (most common)

1. 快速入门——基础编辑（最常用）

python

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

python

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.


该脚本会读取本地文件，将其base64编码后以数据URI形式发送至fal.ai，无需手动发布URL。

2. Quick start — public URL

2. 快速入门——使用公共URL

python

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

python

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:
markdown
```
![edited](output/images/<filename>.png)
```

On Telegram / WeChat: send via

send_to_telegram(file_path="output/images/...", message_type="image")

send_to_wechat(file_path="output/images/...", message_type="image")

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

使用每张图片的
```
local_path
```
（例如
```
output/images/xxx.png
```
）——脚本在执行成功后总会自动下载文件。
告知用户文件已保存至
```
output/images/
```
，可在工作区文件面板中查看。
在Web渠道中，将图片嵌入聊天内容以便用户预览：
markdown
```
![edited](output/images/<filename>.png)
```

在Telegram/微信渠道中，通过

send_to_telegram(file_path="output/images/...", message_type="image")

或

send_to_wechat(file_path="output/images/...", message_type="image")

发送图片。

3. Parameters

3. 参数说明

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

image_url

must be provided. If both are given,

image_path

takes priority.

参数	是否必填	默认值	描述
`image_path`	是*	—	源图像在工作区的本地文件路径
`image_url`	是*	—	源图像的公开HTTPS URL
`prompt`	否	auto	编辑指令（需修改的内容）
`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. Actions — operation types

4. 操作类型

F: Multi-image / general editing

F: 多图像/常规编辑

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

操作	标识	描述
常规编辑	`edit`	根据提示词修改图像
图像合成	`blend`	将人物/主体放置到新背景或场景中
图像扩展	`extend`	扩展图像边界，生成超出原范围的内容
局部编辑	`local_edit`	仅修改图像的特定区域
文字渲染	`text_render`	在图像中添加或修改文字
多角度生成	`multi_angle`	基于单张照片生成不同视角的图像
前后对比	`before_after`	生成并排对比图

G: Professional editing

G: 专业编辑

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

操作	标识	描述
背景替换	`replace_bg`	替换背景，同时保留主体
超分辨率	`upscale`	放大并提升图像分辨率
老照片修复	`restore`	修复老照片的划痕、破损和褪色问题
上色	`colorize`	为黑白照片添加真实色彩
人物移除	`remove_person`	从照片中移除特定人物

V: Retouching / beauty

V: 人像修图/美颜

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

操作	标识	描述
人像修图	`retouch`	磨皮、瑕疵去除、牙齿美白
瘦脸瘦身	`slim`	微调面部和身体比例
图像增强	`enhance`	色彩校正、光线优化、画质提升
艺术滤镜	`filter`	应用特定艺术风格或滤镜效果

W: Medical / fitness comparison

W: 医疗/健身对比

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

操作	标识	描述
效果对比	`comparison`	生成医疗、健身或其他改造场景的前后对比图

X: Automotive

X: 汽车相关

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

操作	标识	描述
汽车改色	`car_color`	更改车辆颜色
汽车贴膜预览	`car_wrap`	可视化车辆贴膜效果

5. Model selection guide

5. 模型选择指南

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.

python

undefined

模型	标识	速度	质量	适用场景
NanoPro	`nanopro`	~25秒	良好	所有请求的默认选项，快速迭代
GPT Image 2	`gpt`	~150秒	最佳	用户明确要求“最高质量”或编辑需要精准保留细节的场景（例如复杂文字渲染、精细修复）

决策规则：

默认选择：除非用户明确要求更高质量，否则始终使用
```
nanopro
```
。
使用
gpt
的场景：用户提到“最高质量”“最佳质量”“ premium”，或编辑需要精准保留细节时。
使用
nanopro
的场景：用户需要快速结果、正在迭代编辑内容，或编辑操作简单直接时。

python

undefined

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

---

result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg", model="gpt")

---

6. Intent recognition guide

6. 意图识别指南

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

用户表述	操作	提示词建议
"编辑这张照片"、"修改这张图片"	`edit`	将用户指令直接作为提示词
"把我放到海滩上"、"更换场景"	`blend`	描述目标场景
"扩展图像"、"把它弄宽"、"outpaint"	`extend`	描述需要添加的内容
"只改衬衫颜色"、"仅编辑天空部分"	`local_edit`	指定修改区域和内容
"添加文字"、"在图片上写'Hello'"	`text_render`	指定文字内容和位置
"展示侧面视角"、"不同角度"	`multi_angle`	描述期望的视角
"前后对比"、"展示差异"	`before_after`	描述转换内容

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

用户表述	操作	提示词建议
"移除背景"、"更换背景"、"换背景"	`replace_bg`	描述新背景
"放大"、"提升分辨率"、"增强画质"	`upscale`	可选择性指定目标画质
"修复老照片"、"修复破损照片"、"修复老照片"	`restore`	描述具体破损问题
"上色"、"给黑白照片加颜色"、"上色"	`colorize`	可选择性描述预期色彩
"移除这个人"、"P掉某人"	`remove_person`	描述需要移除的人物

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

用户表述	操作	提示词建议
"修图"、"磨皮"、"去除瑕疵"、"磨皮美白"	`retouch`	指定修图程度
"让我瘦一点"、"瘦脸"、"瘦脸"	`slim`	指定调整区域
"增强色彩"、"优化光线"、"调色"	`enhance`	描述期望效果
"应用滤镜"、"做成复古风格"、"滤镜"	`filter`	描述滤镜风格

Medical / fitness

医疗/健身对比

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

用户表述	操作	提示词建议
"手术前后对比"、"健身效果变化"	`comparison`	描述转换场景

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

用户表述	操作	提示词建议
"更改汽车颜色"、"改成红色"、"汽车改色"	`car_color`	指定目标颜色和漆面效果
"汽车贴膜"、"改色膜预览"、"贴膜预览"	`car_wrap`	描述贴膜材质和颜色

7. Prompt engineering best practices

7. 提示词工程最佳实践

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

python

result = edit_image(
    image_path="photo.jpg",
    prompt="a beautiful sunset beach with palm trees and golden light",
    action="replace_bg",
)

每个操作都有内置的提示词模板，会自动将用户指令包装为优化后的内容以获得最佳结果。你只需传递用户的具体需求，模板会自动添加技术层面的质量要求。

例如，用户要求“把背景改成日落海滩”：

python

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

脚本会将其包装为："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..."

undefined

undefined

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"

明确描述修改内容——模糊的提示词会导致效果不佳：
- ❌ "让它更好看"
- ✅ "提高对比度，添加暖金色调，锐化细节"
说明需要保留的内容——尤其是局部编辑场景：
- ❌ "更换衬衫"
- ✅ "将衬衫颜色改为海军蓝，保留原有面料纹理和褶皱"
指定材质和效果——适用于汽车和产品编辑：
- ❌ "改成蓝色"
- ✅ "深邃金属蓝，搭配亮面清漆效果"
参考现实风格——适用于滤镜和艺术效果：
- ❌ "做成艺术风格"
- ✅ "应用Wes Anderson电影风格的暖色调电影调色"
为修复/上色指定年代：
- ❌ "给这个上色"
- ✅ "为这张1940年代的家庭照片上色，使用符合时代的服装色彩"
修图时指定程度：
- 轻度："轻微磨皮，保留自然纹理"
- 中度："专业修图，去除瑕疵，均匀肤色"
- 重度："全面美颜修图，磨皮、提亮眼睛、美白牙齿"

8. Usage examples by scenario

8. 场景使用示例

Background replacement

背景替换

python

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

python

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

undefined

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

undefined

Old photo restoration

老照片修复

python

undefined

python

undefined

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

undefined

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

undefined

Portrait retouching

人像修图

python

undefined

python

undefined

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

undefined

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

undefined

Image enhancement

图像增强

python

undefined

python

undefined

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

undefined

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

undefined

Super-resolution upscaling

超分辨率放大

python

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

python

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

人物移除

python

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

python

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)

图像扩展（Outpainting）

python

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

python

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

汽车定制

python

undefined

python

undefined

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

undefined

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

undefined

Before/after comparison

前后对比图

python

undefined

python

undefined

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

undefined

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

undefined

Local editing

局部编辑

python

undefined

python

undefined

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

undefined

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

undefined

Text rendering

文字渲染

python

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

python

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

高质量编辑

python

undefined

python

undefined

Use GPT model for best quality

使用GPT模型获取最佳质量

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

---

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

9. 提供的脚本

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.

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

10. Local testing

10. 本地测试

Set

FAL_KEY

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

bash

undefined

设置

FAL_KEY

环境变量，直接调用fal.ai（绕过sc-proxy）：

bash

undefined

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]

参数：<image_path_or_url> [prompt] [action] [model]

---

---

11. Troubleshooting

11. 故障排查

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
Background not fully removed	Use `replace_bg` action with explicit background description
Retouching looks unnatural	Add "keep natural texture" or "subtle" to prompt

问题	解决方法
`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"` 获取更高质量；提示词更具体
背景未完全移除	使用 `replace_bg` 操作并明确描述背景
修图效果不自然	在提示词中添加“保留自然纹理”或“轻微”

12. Infrastructure (reference)

12. 基础架构（参考）

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.

调用方 →
```
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
```

Model endpoints

模型端点

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

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