flux-kontext

用途

Flux Kontext Pro 用于对单张源图片进行精确的局部编辑。它是 Black Forest Labs 的 Flux 1 Kontext Pro 模型，托管在 RunComfy Model API 上，特点是通过提示词实现强控制、输出一致、保真度高。该技能把这一编辑能力封装为可通过 RunComfy CLI 调用的形式。

主要能力

单张参考图的精确局部编辑，例如“她现在手里拿着一把橙色雨伞”。
在定向修改的同时，高保真保留源图中的主体身份。
单张图片上的快速迭代：简短提示词加单张参考图即可形成快速结果循环。
品牌素材的文字或颜色替换：使用带引号的文本配合前置的“保持不变”指令效果较好。

使用方式

前置条件

RunComfy CLI：npm i -g @runcomfy/cli
RunComfy 账号：runcomfy login 会打开浏览器设备码流程。
CI / 容器环境：改用环境变量 RUNCOMFY_TOKEN=<token>，而非 runcomfy login。

端点与输入字段

端点：blackforestlabs/flux-1-kontext/pro/edit

字段	类型	必填	默认值	说明
prompt	string	是	—	单条声明式编辑指令。
image	string	是	—	单张源图片 URL（可公开抓取的 HTTPS）。
aspect_ratio	enum	否	(input)	从模型页面支持的 W:H 选项中选取。
seed	int	否	—	可复用以进行变体对比。

该 schema 刻意保持精简——Kontext 依赖提示词加单张参考图。若需要多图或联网联动的编辑，应改用 Nano Banana Edit。

调用示例

默认——局部编辑，保留其余部分不变：

runcomfy run blackforestlabs/flux-1-kontext/pro/edit \
  --input '{
    "prompt": "Keep the person'\''s face, pose, and clothing unchanged. Add an orange umbrella in her left hand and a slight smile.",
    "image": "https://.../portrait.jpg"
  }' \
  --output-dir <absolute/path>

带 seed 的可复现变体系列：

runcomfy run blackforestlabs/flux-1-kontext/pro/edit \
  --input '{
    "prompt": "Keep the bottle, label, and lighting unchanged. Replace the brand text on the label from \"ALPHA\" to \"AURA\".",
    "image": "https://.../bottle.jpg",
    "seed": 42
  }' \
  --output-dir <absolute/path>

提示词写法

一条声明式指令。Kontext 在类似官方文档示例的提示词上表现最佳："She is now holding an orange umbrella and smiling"。使用祈使语气，只做一处修改。
保留优先。先写 "Keep [identity / pose / framing / brand] unchanged."，再写要做的修改。模型会遵循前置声明的内容。
仅单张参考图——选对那一张。这里不支持多图并行。若有多张参考图，先确定主图并传入该张。多图流程请改用 Nano Banana Edit。
小步迭代。如果 Kontext 出现漂移，把复合编辑拆成多次串行的单指令编辑（第一遍改背景，第二遍改服装）。
宽高比——从支持的枚举中选取。列表之外的值会返回 422 或被裁剪。

反模式：

复合式提示词（"change A and add B and remove C"）→ 漂移。
试图向多张源图并行展开 → 用错模型（应使用 Nano Banana Edit）。
使用被动语态书写的提示词 → 可靠性较低。
在没有源图的情况下要求全新构图 → 用错模型（应使用 Flux 2 Klein 文生图）。

适用场景

用例	为何选择 Flux Kontext
单次精确局部编辑	专为此设计；高保真
在定向修改中保留源主体身份	在明确指令下保留能力强
品牌素材文字或颜色替换	带引号文本加前置保留指令效果好
单图快速迭代	简短提示词加单张参考图等于快速结果循环

示例提示词（经验证可产生较好结果）：

页面示例：

She is now holding an orange umbrella and smiling

保留前置的品牌编辑：

Keep the bottle silhouette, table, and lighting exactly as in the input.
Replace only the brand text on the label, from "ALPHA" to "AURA".
Same font weight, white on black, centered.

构图微调：

Keep the person's face, pose, and clothing unchanged. Add a leather
shoulder bag, dark brown, hanging on the right shoulder.

局限

仅支持单张源图。多图流程请使用 Nano Banana Edit（1–20 张）。
公开的 RunComfy 文档较简略——除 prompt、image、aspect_ratio、seed 之外可能还存在其他 schema 字段；请查看模型页面以获取最新字段列表。
复合提示词会漂移——请拆分为串行的多次编辑。
多语言或图内嵌入文字的编辑，通常 GPT Image 2 edit 更胜一筹。

退出码

code	含义
0	成功
64	CLI 参数错误
65	输入 JSON 错误 / schema 不匹配
69	上游 5xx
75	可重试：超时 / 429
77	未登录或 token 被拒

完整参考：docs.runcomfy.com/cli/troubleshooting。

工作原理

该技能调用 runcomfy run blackforestlabs/flux-1-kontext/pro/edit，并附带符合 schema 的 JSON body。CLI 会 POST 到 https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit，轮询请求，获取结果，并把任何 .runcomfy.net / .runcomfy.com URL 下载到 --output-dir。Ctrl-C 会在退出前取消远程请求。

安全与隐私

Token 存储：runcomfy login 会把 API token 写入 ~/.config/runcomfy/token.json，权限模式为 0600（仅所有者可读写）。在 CI / 容器中设置 RUNCOMFY_TOKEN 环境变量可完全绕开该文件。
输入边界：用户提示词以 JSON 字符串形式通过 --input 传给 CLI。CLI 不会对提示词做 shell 展开；它直接通过 HTTPS 把 JSON body 发送到 Model API。提示词内容不构成 shell 注入面。
第三方内容：传入的 image / mask / video URL 由 RunComfy 模型服务器抓取，而非本机 CLI。应把外部 URL 视为不可信；基于图像的提示词注入是任何图像编辑 / 视频编辑模型已知的风险。
出站端点：仅 model-api.runcomfy.net（提交请求）以及 *.runcomfy.net / *.runcomfy.com（生成产物的下载白名单）。无遥测，无回调。
生成文件大小上限：CLI 会中止任何超过 2 GiB 的单个下载，以防恶意或失控的模型输出写满磁盘。

模型选择参考

你需要	使用
单图精确局部编辑（"she's now holding X"）	Flux Kontext
高保真保留源主体身份	Flux Kontext
跨 1–20 张图片的批量编辑	Nano Banana Edit
编辑图像中的多语言 / 嵌入文字	GPT Image 2 edit
无源图的全新生成	Flux 2 Klein

若用户明确提到 "Flux Kontext" / "kontext" / "BFL Kontext"，无论其他条件如何都路由到这里。