Image Edit — Pro Pack on RunComfy

runcomfy.com · Nano Banana Edit · GPT Image 2 Edit · Flux Kontext · Z-Image Inpaint · GitHub

Image edit, intent-routed. This skill doesn't lock you to one model — it picks the right edit model in the RunComfy catalog based on what the user actually wants: batch identity-preservation, multilingual text rewrite, single-shot precise edit, or mask-driven region replacement.

npx skills add agentspace-so/runcomfy-skills --skill image-edit -g

Pick the right model for the user's intent

The agent reads this table, classifies the user's intent, and picks the matching subsection below.

Prerequisites

1. RunComfy CLI — npm i -g @runcomfy/cli
2. RunComfy account — runcomfy login.
3. CI / containers — set RUNCOMFY_TOKEN=<token>.

---

Route 1: Nano Banana Edit — default for general edit + batch

Model: google/nano-banana-2/edit

Schema

Invoke

runcomfy run google/nano-banana-2/edit \
  --input '{
    "prompt": "Keep the subject identity, pose, and clothing unchanged. Convert the background into a rainy neon cyberpunk street.",
    "image_urls": ["https://.../portrait.jpg"]
  }' \
  --output-dir <absolute/path>

Batch (lock aspect + resolution):

runcomfy run google/nano-banana-2/edit \
  --input '{
    "prompt": "Replace the watermark in the bottom-right with the text \"AURA\" in clean white sans-serif. Keep everything else exactly as in the input.",
    "image_urls": ["https://.../sku-1.jpg", "https://.../sku-2.jpg", "https://.../sku-3.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }' \
  --output-dir <absolute/path>

Prompting tips

• Preservation first: "Keep [identity / pose / brand / framing] unchanged." Then state the change.
• Spatial scope: "background only", "the left object", "upper-right quadrant" — concrete locations honored.
• Batch consistency: lock aspect_ratio and resolution across the batch.
• Iterate small: split compound edits into multiple shorter passes.

---

Route 2: GPT Image 2 Edit — multilingual text + multi-ref composition

Model: openai/gpt-image-2/edit

Schema

Invoke

Multilingual text rewrite:

runcomfy run openai/gpt-image-2/edit \
  --input '{
    "prompt": "Keep the photograph, layout, and brand mark exactly as in the input. Replace only the in-image headline. The new headline reads \"今日のおすすめ\" in bold Japanese kana, same position and font weight.",
    "images": ["https://.../poster-en.jpg"]
  }' \
  --output-dir <absolute/path>

Multi-ref composition:

runcomfy run openai/gpt-image-2/edit \
  --input '{
    "prompt": "Compose subject from image 1 into the room from image 2. Match the lighting and color palette of image 2. Keep image 1 subject identity unchanged.",
    "images": ["https://.../subject.jpg", "https://.../room.jpg"]
  }' \
  --output-dir <absolute/path>

Prompting tips

• Quote in-image text exactly. Name the script for non-Latin: "Japanese kana", "Cyrillic", "Arabic right-to-left".
• Number multi-refs: "subject from image 1, lighting from image 2".
• Directional layout language: "move the headline from top-right to bottom-center", "replace the watermark in the bottom-right".
• size: "auto" preserves input ratio — recommended unless the edit changes framing.

---

Route 3: Flux Kontext Pro — single-shot precise local edit

Model: blackforestlabs/flux-1-kontext/pro/edit

Schema (minimal)

Single image only — no array. For multi-image flows, use Route 1 (Nano Banana Edit).

Invoke

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>

Prompting tips

• One declarative instruction. "She is now holding an orange umbrella and smiling" — imperative, single change.
• Preservation first. Lead with "Keep [unchanged elements]" then state the change.
• Iterate small. Compound edits drift on a single pass; split into sequential passes.

---

Route 4: Z-Image Turbo Inpaint — mask-driven precise region edit

Model: tongyi-mai/z-image/turbo/inpainting

Schema

Invoke

Object removal (low strength):

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "Remove overhead cables; preserve rooflines and sky gradient; thin clean sky.",
    "image": "https://.../street.jpg",
    "mask_image": "https://.../cables-mask.png",
    "strength": 0.5,
    "control_scale": 0.8
  }' \
  --output-dir <absolute/path>

Region replacement (high strength):

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "Replace busy backdrop with smooth light gray studio paper; mask background only.",
    "image": "https://.../product.jpg",
    "mask_image": "https://.../bg-mask.png",
    "strength": 0.9
  }' \
  --output-dir <absolute/path>

Prompting tips

• A mask URL is required — grayscale, white = inpaint region, black = preserve. Slight blur on mask edges (1–3px) blends better than sharp binary.
• Strength by intent: 0.3–0.5 for retouching / cleanup, 0.6–0.7 for object replacement with style match, 0.8–1.0 for full-region replacement.
• Name what stays outside the mask in the prompt: "preserve rooflines and sky gradient", "match brick pattern and mortar tone".
• Spatial labels still help even though the mask defines the region: "the left shelf", "upper-right quadrant".

---

Limitations

• Each route inherits its model's limits. Nano Banana: 1–20 inputs, 1–4 outputs. GPT Image 2 Edit: up to 10 refs, 4 fixed sizes. Flux Kontext: single ref. Z-Image Inpaint: mask required.
• No multi-route blending. This skill picks one model per call.
• Brand-specific overrides — if the user named a specific model, route to the corresponding brand skill (gpt-image-edit, flux-kontext, nano-banana-edit) for fuller treatment.

Exit codes

Full reference: docs.runcomfy.com/cli/troubleshooting.

How it works

The skill picks one of Nano Banana Edit / GPT Image 2 Edit / Flux Kontext Pro / Z-Image Turbo Inpaint based on user intent and invokes runcomfy run <model_id> with the matching JSON body. The CLI POSTs to the Model API, polls the request, fetches the result, and downloads any .runcomfy.net/.runcomfy.com URL into --output-dir. Ctrl-C cancels the remote request before exit.

Security & Privacy

• Token storage: runcomfy login writes the API token to ~/.config/runcomfy/token.json with mode 0600 (owner-only read/write). Set RUNCOMFY_TOKEN env var to bypass the file entirely in CI / containers.
• Input boundary: the user prompt is passed as a JSON string to the CLI via --input. The CLI does NOT shell-expand the prompt; it transmits the JSON body directly to the Model API over HTTPS. No shell injection surface from prompt content.
• Third-party content: image / mask / video URLs you pass are fetched by the RunComfy model server, not by the CLI on your machine. Treat external URLs as untrusted; image-based prompt injection is a known risk for any image-edit / video-edit model.
• Outbound endpoints: only model-api.runcomfy.net (request submission) and *.runcomfy.net / *.runcomfy.com (download whitelist for generated outputs). No telemetry, no callbacks.
• Generated-file size cap: the CLI aborts any single download > 2 GiB to prevent disk-fill from a malicious or runaway model output.