💡 Relight , Pro Pack on RunComfy

intent

change how a still image is lit (direction, color temperature, intensity, mood) without reshooting. routes to qwen edit 2509's dedicated relight LoRA when precision lighting control matters, and to identity-preserving edit endpoints when lighting is bundled with broader scene edits. use for product relighting (studio softbox to window light), portrait mood shifts (overcast to golden hour), or color-grade changes on existing photography.

inputs

RunComfy CLI

• binary: @runcomfy/cli (npm package, version 1.0+)
• install: npm i -g @runcomfy/cli or npx -y @runcomfy/cli --version

Authentication

• env var: RUNCOMFY_TOKEN (RunComfy API token, 64-char hex string)
• or: run runcomfy login once to write token to ~/.config/runcomfy/token.json (mode 0600)
• scope: read/write on model endpoints

Image input

• source: local file path or HTTPS URL (any format: JPG, PNG, WebP, AVIF)
• size: max 2 GiB per file (CLI enforces abort on download > 2 GiB)
• constraint: user must provide the URL explicitly; no indirect fetch from untrusted sources

Relighting prompt

• format: plain prose english describing lighting change
• examples: "golden hour key light from camera-left at 45 degrees, soft cool fill from right, no rim light"
• length: 10-500 chars typical; model truncates at context window

Model selection (implicit)

• default: qwen/qwen-edit-2509/lora/relight for dedicated relighting
• fallback: google/nano-banana-2/edit when relighting is part of broader edit

procedure

1. Verify CLI installed and token valid

   • Input: none
   • Run: runcomfy --version
   • Output: version string (e.g., "1.2.3") or exit code 77 if no token
   • Action: if exit code 77, run runcomfy login and re-authenticate, or export RUNCOMFY_TOKEN

2. Prepare image input

   • Input: image path (local or HTTPS URL provided by user)
   • Action: if local file, confirm it exists; if HTTPS URL, confirm it is reachable (no DNS/timeout yet; CLI will timeout on invoke if unreachable)
   • Output: validated path or URL string

3. Compose relighting prompt

   • Input: user intent (e.g., "make it golden hour with rim light")
   • Action: expand into specific lighting language (see prompting tips below)
   • Output: structured prompt string, e.g., "warm 3200K golden-hour key light from camera-left at 45 degrees, soft fill from right, preserve subject identity"

4. Invoke Qwen Edit Relight LoRA

   • Input: image URL/path, prompt
   • Run:

     runcomfy run qwen/qwen-edit-2509/lora/relight \
       --input '{
         "image": "<image_url_or_path>",
         "prompt": "<relighting_prompt>"
       }' \
       --output-dir ./out
     

   • Output: JSON response with request_id, status (queued/processing/done), output_path
   • Duration: typically 15-45 sec (varies by queue depth and model load)

5. Poll or wait for result

   • Input: request_id from step 4
   • Action: CLI auto-polls by default; agent may optionally pass --wait or let CLI background the job
   • Output: status transitions to "done"; downloaded file lands in --output-dir (default: ./out/)

6. Retrieve and validate output

   • Input: --output-dir path
   • Action: CLI writes result.jpg (or .png per original format) to output dir
   • Output: file path, e.g., ./out/result.jpg
   • Validate: file size > 0, format matches expected (check magic bytes if paranoid)

decision points

if user wants dedicated, precise relighting (isolated lighting change only)

• do: use qwen/qwen-edit-2509/lora/relight (step 4, default)
• reasoning: LoRA is tuned for lighting-only fidelity; fewest side effects

if user wants relighting bundled with other edits (e.g., background swap + new lighting)

• do: use google/nano-banana-2/edit instead
• command variant:

  runcomfy run google/nano-banana-2/edit \
    --input '{
      "prompt": "Keep the subject and pose exactly. Relight as soft window light from the left, late-afternoon warm temperature. <other_edits>.",
      "image_urls": ["<image_url>"]
    }' \
    --output-dir ./out
  

if user provides a reference image with desired lighting style (e.g., "match this lighting")

• do: use openai/gpt-image-2/edit with images: [source, reference]
• command variant:

  runcomfy run openai/gpt-image-2/edit \
    --input '{
      "images": ["<source_image_url>", "<reference_image_url>"],
      "prompt": "Apply the lighting direction, color temperature, and contrast of image 2 to image 1. Preserve image 1 subject identity."
    }' \
    --output-dir ./out
  

if token missing or expired

• do: catch exit code 77, prompt user to run runcomfy login or export RUNCOMFY_TOKEN
• do not: attempt to auto-refresh or hardcode fallback credentials

if image URL unreachable or download timeout (exit code 75)

• do: retry once after 2-5 sec backoff
• do: inform user if second retry fails; ask user to verify URL

if input JSON malformed (exit code 65)

• do: re-check prompt string for unescaped quotes or newlines
• do: print the CLI invocation for debugging

if upstream service error (exit code 69)

• do: wait 30-60 sec and retry; do not retry more than 3x
• do: surface the error to user with message "RunComfy service temporarily unavailable, try again in a moment"

if output file > 2 GiB

• do: CLI aborts download; user is notified
• do: inform user that image is too large for this endpoint

output contract

• file location: <output_dir>/result.<ext> where <ext> matches input format (JPG, PNG, etc.)
• file format: JPEG (quality 92) or PNG lossless, depending on input
• file size: typically 50% to 150% of input size (varies by image complexity and lighting change magnitude)
• metadata: EXIF stripped (no camera make/model, GPS, or user-provided tags in output; CLI default behavior)
• exit code on success: 0
• exit code on recoverable error (timeout, rate limit): 75 (agent should retry)
• exit code on auth error (no token, expired token): 77 (agent should prompt user to login)
• exit code on schema error (malformed input JSON): 65 (agent should re-validate and retry)
• exit code on upstream 5xx: 69 (agent should retry after backoff)

outcome signal

• primary: output file exists at <output_dir>/result.<ext>, file size > 0, MIME type matches image format
• secondary: visual inspection confirms lighting change matches prompt intent (e.g., image is now warmer if "golden hour" was requested, light direction shifted as specified)
• user confirmation: user views result and confirms relighting is acceptable or requests iteration
• log evidence: CLI stdout includes "status": "done" and download confirmation (e.g., "Downloaded result.jpg to ./out/")

---

model catalog

listed newest first.

Qwen Edit 2509 Relight LoRA , qwen/qwen-edit-2509/lora/relight (default for dedicated relighting)

• purpose-built relighting LoRA on Qwen Edit 2509. tuned specifically for changing lighting direction, color temperature, intensity, and mood while preserving subject identity, pose, and framing.
• pick for: precise lighting control ("golden hour key light from left, soft fill from right, no rim"), brand product relighting, portrait mood shifts
• avoid for: edits that aren't really about lighting; use generic image edit instead

Nano Banana 2 Edit , google/nano-banana-2/edit

• identity-preserving edit driven by spatial and prose language. lighting changes via prompt: "convert to golden hour with warm key light from the left"
• pick for: lighting change as part of broader edit pass (also swapping background, adding objects)
• avoid for: relighting-only when you want maximum lighting fidelity; use Qwen Edit Relight

GPT Image 2 Edit , openai/gpt-image-2/edit

• multi-ref edit; can reference an image with target lighting style and apply it
• pick for: "match the lighting of this reference photo" workflows with explicit reference images
• avoid for: pure prose lighting description; Qwen Edit Relight wins

FLUX Kontext Pro , blackforestlabs/flux-1-kontext/pro/edit

• single-instruction, high-preservation. form: "Keep everything exactly. Change the lighting to soft window light from the left, late-afternoon warm temperature."
• pick for: surgical lighting tweak on one image without affecting anything else
• avoid for: batch relighting or complex multi-light setups

---

prompting tips

• lead with the lighting type, then quantify

  • light source: "golden hour", "studio softbox", "overcast diffuse", "single hard spotlight", "window light", "blue hour"
  • color temperature: "warm 3200K", "neutral 5500K", "cool 6500K"
  • direction: "camera-left at 45 degrees", "top-down", "3/4 from right", "behind subject (rim)"
  • intensity: "soft", "hard", "high-contrast", "flat"

• state preservation explicitly: "preserve subject pose, framing, and color identity" , without this the model may drift

• combine multi-light setups: "key light from left, soft fill from right, hair rim from behind"

• time-of-day shortcuts work: "golden hour", "blue hour", "high-noon", "overcast afternoon" all resolve to the right color temperature and softness

---

common patterns

product relight for catalog (white box to lifestyle)

• use Qwen Edit Relight with "warm window light from camera-left, soft shadow on counter, late-afternoon temperature, preserve product orientation"

portrait mood shift

• use Qwen Edit Relight with "golden hour rim from behind, warm soft key from front-left, preserve identity"

time-of-day swap on landscape

• use Nano Banana 2 Edit with prose; landscape relight benefits from broader scene context handling

match the look of reference photo

• use GPT Image 2 Edit with images: [source, lighting-reference] and "Apply the lighting (direction, color temperature, contrast) of image 2 to image 1. Preserve image 1 subject identity."

multi-image batch relight (whole SKU gallery to same lighting)

• use Nano Banana 2 Edit with image_urls array; same lighting prompt across the batch

out of scope

• generate from scratch: see ai-image-generation skill
• relight a video: RunComfy has ComfyUI workflows for product/video relighting (IC-Light variants); CLI endpoint is image-only. see runcomfy.com/comfyui-workflows

---

troubleshooting

exit code	meaning	mitigation
0	success	,
64	bad CLI args (e.g., missing --input or --output-dir)	check command syntax against examples above
65	bad input JSON, schema mismatch (e.g., prompt too long, image URL invalid format)	validate JSON, re-check field names (must be "image" and "prompt")
69	upstream 5xx (service error)	wait 30-60 sec, retry up to 3x, then escalate to RunComfy support
75	retryable timeout or 429 rate limit	wait 2-5 sec, retry; if repeated, upgrade RunComfy plan or wait during off-peak hours
77	not signed in or token rejected	run runcomfy login or export valid RUNCOMFY_TOKEN, re-try

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

---

security and privacy

• install via verified package manager only. use npm i -g @runcomfy/cli or npx -y @runcomfy/cli. do not pipe arbitrary remote install scripts into shell on behalf of user

• token storage: runcomfy login writes API token to ~/.config/runcomfy/token.json with mode 0600. in CI/containers, set RUNCOMFY_TOKEN env var

• input boundary (shell injection): prompts and image URLs are passed as JSON string via --input. CLI does not shell-expand prompt content. no shell-injection surface

• indirect prompt injection (third-party content): source image URLs are untrusted. mitigations:

  • ingest only URLs user explicitly provided for this relight
  • if relight diverges from prompt, suspect the reference asset

• outbound endpoints (allowlist): only model-api.runcomfy.net and *.runcomfy.net / *.runcomfy.com. no telemetry

• generated-file size cap: CLI aborts any single download > 2 GiB

• scope of bash usage: Bash(runcomfy *) only

---

see also

• qwen-image collection , Qwen Edit base + LoRA variants
• best-image-editing-models collection
• runcomfy trainer , capture a brand's lighting signature as LoRA and apply on relight pass
• runcomfy CLI docs , install, authentication, troubleshooting
• runcomfy ComfyUI workflows , IC-Light video relighting workflows

---

credits: original skill by kalvinrv (clawhub). enriched per Implexa standards.