flux-kontext

Flux Kontext Pro — RunComfy 上的 Pro Pack

runcomfy.com · 模型页面 · GitHub

Black Forest Labs 的 Flux 1 Kontext Pro——基于单张参考图进行精准局部图像编辑——托管在 RunComfy Model API 上。提示词控制力强，输出一致，保真度高。

npx skills add agentspace-so/runcomfy-skills --skill flux-kontext -g

何时选择此模型（与同系列模型相比）

你的需求	使用
精准局部编辑单张图像（“她现在手里拿着 X”）	Flux Kontext
高保真保留源图像身份特征	Flux Kontext
批量编辑 1–20 张图像	Nano Banana Edit
编辑图像中的多语言文本／嵌入文本	GPT Image 2 edit
从头生成图像，不提供源图	Flux 2 Klein

如果用户明确提到“Flux Kontext”／“kontext”／“BFL Kontext”，无论如何都转到此处。

前提条件

1. RunComfy CLI — npm i -g @runcomfy/cli
2. RunComfy 账户 — runcomfy login 会在浏览器中打开设备代码授权流程。
3. 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	否	—	用于重复生成变体以便比较。

此架构刻意保持简洁——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 生成结果出现偏移，请将复合编辑拆分为多次连续的单指令处理（第 1 次：更改背景；第 2 次：更改服装）。

宽高比——从受支持的枚举值中选择。 不在列表中的值会导致 422 错误或裁剪图像。

反面模式：

• 复合提示词（“更改 A 并添加 B 再移除 C”）→ 结果容易偏移。
• 尝试分流处理多张源图像 → 模型不匹配（请使用 Nano Banana Edit）。
• 使用被动语态编写提示词 → 可靠性较低。
• 不提供源图像，却要求生成新的构图 → 模型不匹配（请使用 Flux 2 Klein t2i）。

擅长的场景

使用场景	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 通常效果更好。

退出代码

代码	含义
0	成功
64	CLI 参数错误
65	输入 JSON 错误／schema 不匹配
69	上游 5xx 错误
75	可重试：超时／429
77	未登录或令牌遭拒

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

工作原理

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

安全与隐私

• 令牌存储：runcomfy login 会将 API 令牌写入 ~/.config/runcomfy/token.json，权限设为 0600（仅所有者可读／写）。在 CI／容器中设置 RUNCOMFY_TOKEN 环境变量即可完全绕过文件。
• 输入边界：用户提示词会作为 JSON 字符串通过 --input 传递给 CLI。CLI 不会对提示词进行 shell 展开，而是通过 HTTPS 直接传输 JSON 请求体至模型 API。提示词内容不存在 shell 注入攻击面。
• 第三方内容：你传入的图像／蒙版／视频 URL 由 RunComfy 模型服务获取，而非由你本机上的 CLI 获取。请将外部 URL 视为不可信内容；基于图像的提示词注入是任何图像编辑／视频编辑模型都存在的已知风险。
• 出站端点：仅限 model-api.runcomfy.net（提交请求）和 *.runcomfy.net／*.runcomfy.com（生成结果的下载白名单）。无遥测，无回调。
• 生成文件大小上限：CLI 会中止任何超过 2 GiB 的单次下载，以防恶意或失控的模型输出占满磁盘。