🫧 Image Edit — Pro Pack on RunComfy

runcomfy.com · docs · Image edit models

Image edit on RunComfy. This skill is the canonical image edit entry point for the RunComfy Model API: give it a source image and an edit instruction, and it returns the edited image. Image edit on RunComfy means transforming an existing still — swap background, remove an object, rewrite a headline, mask-fill a region — without re-shooting.

What "image edit" means here

Image edit is the task of taking a source image and producing a transformed image that preserves identity, framing, or layout where you want, while changing what you specify. Image edit is distinct from text-to-image (no input) and from image-to-video (output is a clip). Common image edit operations include:

• Background image edit — swap the background of a portrait, product, or scene while preserving the foreground identity.
• Object-removal image edit — remove cables, watermarks, distracting elements, leaving the rest of the image edit untouched.
• Object-addition image edit — add a new element (umbrella, sign, accessory) to an existing image edit subject.
• Text-rewrite image edit — replace an in-image headline, label, or signage, including multilingual image edit.
• Mask-driven image edit — fill or replace a specific masked region with strength control.
• Multi-ref composition image edit — combine subject from one image with scene/lighting from another.
• Batch image edit — apply the same image edit instruction across 1–20 inputs (SKU galleries, A/B variants).

This skill picks the right image edit endpoint for the user's intent and calls runcomfy run <model>/edit with the matching schema.

When to use image edit on RunComfy

Pick image edit on RunComfy whenever:

• You have an existing image and want to change something about it — image edit is the right task.
• You want identity-stable image edit — the subject, brand, or product from the input must survive into the edited image.
• You're producing batch image edit at scale — SKU galleries, multi-language variant image edit, A/B testing.
• You need mask-precise image edit — region replacement, watermark removal, region fill.
• The user said "image edit", "edit image", "image-to-image", "swap the background", "remove the watermark", "rewrite the headline", or showed an image and asked to transform it — route here.

Image edit routes

The agent reads this table, classifies the user's image edit intent, and picks the matching endpoint.

Prerequisites

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

Default image edit — Nano Banana Edit

The default image edit endpoint. Use for any general image edit task: background swap, object removal, object addition, batch image edit. Up to 20 inputs per image edit call, up to 4K resolution.

Schema

Invoke

Background-swap image edit:

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 image edit (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>

Multilingual image edit — GPT Image 2 Edit

Use when the image edit involves rewriting in-image text (especially non-Latin scripts) or composing from multiple references with layout precision.

Multilingual text-rewrite image edit:

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 image edit:

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>

Single-shot precise image edit — Flux Kontext Pro

Use when the image edit is a single declarative instruction on a single reference image — the most surgical image edit option.

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>

Mask-driven image edit — Z-Image Turbo Inpaint

Use when the image edit is constrained to a specific masked region — object removal, region fill, region replacement. Mask-driven image edit gives the cleanest results when you can supply a precise mask.

Object-removal image edit:

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 image edit:

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 image edit — what works

Image edit prompts behave differently from text-to-image prompts. The source image already fixes most of the look — your image edit prompt should drive the change, not redescribe the source.

• Lead with preservation goals. "Keep [identity / pose / framing / brand] unchanged. Then state the image edit change." Tell the image edit model what NOT to change.
• One image edit direction per call. Compound image edits drift. Pick one bucket — background OR object OR text OR layout — per image edit call.
• Spatial scope language. "background only", "the left object", "upper-right quadrant" — image edit models honor concrete locations.
• Quote in-image text exactly. For text-rewrite image edit, put the literal characters in quotes. Name the script for non-Latin: "Japanese kana", "Cyrillic", "Arabic".
• Number multi-refs in image edit prompts. "Subject from image 1, lighting from image 2" — image edit models route cues correctly when refs are numbered.
• Mask-edge softness. For mask-driven image edit, a 1–3px blur on the mask edge blends cleaner than a sharp binary mask.
• Iterate small. Split compound image edit into multiple shorter passes; consistency is better across passes than within a single overstuffed prompt.

Image edit FAQ

What's the max batch size for image edit? 20 inputs per call on the default image edit endpoint (Nano Banana Edit). Other image edit routes are single-input.

What image formats does image edit accept? JPEG, PNG, WebP. Source URLs must be publicly fetchable HTTPS.

Does image edit preserve subject identity? Yes — all four image edit routes are designed for identity preservation. Always state the goal: "keep face identity unchanged".

Can image edit rewrite text in non-Latin scripts? Yes — route to GPT Image 2 Edit. It handles Japanese kana, Cyrillic, Arabic, Hangul, Chinese, etc.

What's the highest resolution available for image edit? 4K on Nano Banana Edit. Other image edit routes cap at their respective sizes.

Image edit vs text-to-image on RunComfy? Image edit transforms an existing image. Text-to-image starts from a prompt only. Use image edit when you have a source; use text-to-image for novel content.

Can I do mask-free region image edit? Yes — most image edit routes work without an explicit mask. Use spatial language ("upper-right corner", "the background only"). For surgical region image edit, provide a mask via the Z-Image inpaint route.

Can I run multiple image edits in one call? Within Nano Banana Edit's batch (1–20 inputs with the same instruction), yes. For different image edit instructions, chain calls.

Limitations

• Each image edit route inherits its model's limits. Nano Banana Edit: 1–20 inputs, 1–4 outputs. GPT Image 2 Edit: up to 10 refs, 4 fixed sizes. Flux Kontext Pro: single ref. Z-Image Inpaint: mask required.
• No multi-route image edit blending. This skill picks one image edit 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) instead of forcing it through this image edit router.

Exit codes

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

How it works

The skill picks one of four image edit endpoints (Nano Banana Edit / GPT Image 2 Edit / Flux Kontext Pro / Z-Image Turbo Inpaint) based on user intent, and invokes runcomfy run <model>/edit with the matching JSON body. The CLI POSTs to the RunComfy Model API, polls the image edit request status every 2 seconds, and downloads the resulting image edit output from the *.runcomfy.net / *.runcomfy.com URL into --output-dir. Ctrl-C cancels the in-flight image edit request.

Security & Privacy

• Token storage: runcomfy login writes the API token to ~/.config/runcomfy/token.json with mode 0600.
• Input boundary: the image edit prompt is passed as JSON via --input. No shell injection.
• Third-party content: source images and masks are fetched by the RunComfy server. Treat external URLs as untrusted — image-based prompt injection is a known risk for any image edit model.
• Outbound endpoints: only model-api.runcomfy.net and *.runcomfy.net / *.runcomfy.com.
• Generated-file size cap: 2 GiB.