image

image

一项技能，四个动词。你写提示词；该技能负责校验、调用、下载并记住。

python3 - <<'EOF'
import sys; sys.path.insert(0, "skills/image")
from exports import generate, edit, remove_background, inspect, list_models
r = edit("Replace the first letter W of WALL ST with the logo in image 2, matching the sign's paint and perspective",
         ["uploads/sign.png", "uploads/logo.png"],
         keep="every other letter, the sign colour, background and lighting",
         model="nanopro", resolution="2K")
print(r["images"][0]["local_path"] if r["success"] else r["error"])
EOF

始终在 bash 的 python3 - <<'EOF' heredoc 中运行（不要用 python3 -c）。结果 → {"success", "images":[{"local_path","dims"}], "job_dir", "request_id", "cost_usd", "prompt", "params"}；失败时 → {"success": False, "error"}。每个任务都有自己的目录——不会被覆盖。

四个动词

动词	何时使用	关键参数
generate(prompt, model=None, **params)	没有任何可作起点	aspect_ratio、resolution（nanopro）、image_size+quality（gpt）、num_images、seed
edit(prompt, image_paths, keep=, mask_path=, model=, tx_id=, **params)	任何以现有图像为起点的情况——修图、背景、logo/文字、风格、基于参考图的产品/人像/试穿/3D	image_paths[0] 是底图，其余是参考图；在提示词中说明每张图是什么
remove_background(image_path)	干净抠图 → 透明 PNG	—
inspect(images, question, mode=)	编辑前或编辑后需要查看	mode="inspect"（是什么/在哪里/OCR）、"compare"（前后对比）、"qa"（对照 goal+keep 的通过/失败）

list_models() 会告诉你每个模型的真实能力。不确定时读它；不要靠记忆。

选择模型——调用 list_models()，然后：

• 草稿 / 探索 → nano2（最快、最便宜）。
• 默认、多参考图、指令繁重的编辑 → nanopro。除非传入 resolution="2K"|"4K"，否则输出为 1K——当源图较大时始终设置它，否则你会在无意中缩小用户的图像。
• 区域锁定编辑（只改这个区域，其他地方的像素不得移动）→ 使用带 mask_path 的 gpt（白色 = 可编辑）。它是唯一有真正蒙版的模型。速度慢（约 2 分钟）——要如实说明。
• 大量参考图 / 素材合成 → seedream（候选方案：明确写出它的名字）。
• "最佳质量"的要求 → 告诉用户你选了哪个以及为什么；如果预算允许就跑 2 个候选，而不是靠猜。

未知模型、不支持的参数、参考图过多、模型不支持蒙版却传了蒙版 → 调用会在花费之前拒绝。读错误信息；它会列出实际支持的内容。绝不要通过悄悄丢弃某个参数来绕过它——输出尺寸出错就是这样造成的。

防止已知故障的原则

1. 在写提示词之前，先重述目标。 对自己说两句话：改变 = …… ，保留 = …… 。把保留写入 keep=。"替换第一个 W，保留 ALL ST" 在提示词中绝不能变成 "only the letter W"。
2. 为每个参考命名其角色。 "Image 1 是底图。Image 2 是要放置的 logo。Image 3 是颜色参考。" 模型无法从文件顺序推断角色。
3. 精确文字、logo、精确字体 → AI 模型在这方面不可靠。优先做法：用 edit（或蒙版）清除该区域，然后确定性地合成真实矢量/文字（PIL），再可选地做一次 edit 处理 "混合粘贴元素的光照与颗粒"。不要要求扩散模型凭记忆绘制品牌标识。
4. 先查看再循环。 如果你不知道某物在哪里或文字写了什么，用 inspect(..., mode="inspect") 并提出一个具体问题。不要裁剪并询问五次；一个带有坐标请求的好问题就足够了。将返回的框视为近似值。
5. 针对阶段而非最终产品进行 QA。 一张中间状态的 "W 已移除，logo 仍待添加" 图像必须按照那个目标通过 mode="qa"。显式传入 goal= 和 keep=。
6. 自动重试一次，然后询问。 对于多步编辑，开启一个事务（start_transaction(goal, base_path, keep=, logo=..., end_frame=...)），将 tx_id= 传给每次 edit，在你自己的重试上标记 auto_fix=True。预算是 1 次；之后展示候选项，每个附带一行差异说明，让用户选择（approve(tx_id, rev)）。被拒绝的输出永远不会成为下一个底图。
7. 确定性操作保持确定性。 调色、模糊、裁剪、缩放、阴影、透视 —— 用 PIL/OpenCV，而不是付费重新生成。真正的放大 = 通过 resolution/image_size 达到目标像素尺寸，而不是在提示词中写 "upscale" 这个词。
8. 视频帧：起始/结束帧对必须是两个已批准的修订版本。如果视频模型只接受一张图像，请如实说明，而不是寄希望于它。

领域知识

Amazon/Xiaohongshu 的产品图、证件照、试穿措辞、3D 渲染手段、20 个旧编辑操作及其去向 —— references/domain-guides.md（当请求属于这些领域之一时读一次）。

恢复与成本

• 超时或连接中断 → recover(job_id) 重新获取已付费的结果；不要重新提交。
• 费用会自动落在用户的轮次上；每个结果中都有 cost_usd。当 >$0.10 或运行多个候选时请提及。
• 不使用网关的本地测试：设置 FAL_KEY。

边界

真实人物/面孔：用于用户自己的照片可以；拒绝冒充或色情内容。品牌：使用用户提供的素材。当对某人的身份或同意有疑问时，先询问。