BYOK OpenAI image generation and editing nodes for ComfyUI.
Bring your own OpenAI API key — calls go directly to OpenAI, no proxy, no extra credits.

✨ Features

🖼️ Two nodes — Imagent: OpenAI Image (text-to-image) and Imagent: OpenAI Image Edit (edit, inpaint, multi-reference compose).
🤖 Current gpt-image models — gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2.
✍️ Text-to-image with full control over size, quality, background, and output format.
🎨 Edit + inpaint (mask) — supply a mask to repaint a specific region; white pixels mark the area to edit.
🔗 Multi-reference compositing — feed up to 16 reference images to the edit node (auto-growing input).
🎛️ Per-model UI — the model widget is dynamic: switching models swaps the size list and shows only the options that model supports (no invalid combos).
🏞️ Up to 8 images per call — batch generation in a single node execution.
🛡️ Optional content moderation — auto (default) or low.
🔑 BYOK — your own OpenAI API key, your own costs. Unlike ComfyUI's built-in OpenAI nodes (which route through ComfyUI's paid proxy), Imagent calls the OpenAI API directly. No proxy, no per-image credit markup.
🚫 DALL·E intentionally excluded — all DALL·E models were shut down by OpenAI in 2026.

📦 Installation

Requires ComfyUI ≥ 0.23.0 — the nodes use the comfy_api IO schema (DynamicCombo) for the per-model UI.

Option A — ComfyUI Manager (recommended)

Open ComfyUI Manager → Custom Nodes Manager, search for Imagent, click Install, and restart ComfyUI.

Option B — git clone

cd ComfyUI/custom_nodes
git clone https://github.com/agarzon/ComfyUI-Imagent.git
pip install -r ComfyUI-Imagent/requirements.txt

Restart ComfyUI.

🔑 API key

Imagent reads your key in this order:

Environment variable (preferred): set OPENAI_API_KEY before launching ComfyUI.
config.json: copy config.example.json → config.json (gitignored) in the extension directory and add your key.

Note: OpenAI may require API Organization Verification before gpt-image models can be called. If your key is valid but you receive an authorization error, complete verification in the OpenAI dashboard — the error message logged to the ComfyUI console will tell you.

🧩 Nodes

🤖 Imagent: OpenAI Image

Text-to-image generation via images.generate.

Parameter	Type	Values / Notes
`prompt`	STRING	Text description of the image to generate
`model`	DynamicCombo	`gpt-image-2.5-flare` (default), `gpt-image-2.5-sunburst`, `gpt-image-2`. Switching the model swaps the options below.
↳ `size`	COMBO	`auto`, the three base sizes, five high-res presets, and `custom`.
↳↳ `custom_width` / `custom_height`	INT	Appear only when `size = custom`. 480–3840, step 16; both multiples of 16; aspect ≤ 3:1; total pixels 655,360–8,294,400.
↳ `background`	COMBO	gpt-image-2.5: `auto`, `opaque`, `transparent` (needs `png`/`webp`). gpt-image-2: `auto`, `opaque`.
`quality`	COMBO	`auto`, `low`, `medium`, `high`, plus `xhigh` / `max` on gpt-image-2.5 (other models fall back to `high`).
`output_format`	COMBO	`png`, `jpeg`, `webp`
`output_compression`	INT	0–100. Applied only for `jpeg` and `webp`.
`moderation`	COMBO	`auto` (default), `low`. Sent only when not `auto`.
`n`	INT	1–8 images per call

Rows marked ↳ live inside the dynamic model widget (appear only for models that support them); ↳↳ rows are nested one level deeper and appear only when their parent option is selected.

No seed widget: OpenAI's image API has no seed, so it can't make outputs reproducible. ComfyUI's normal input-based caching applies — re-queuing an unchanged graph returns the cached image; change the prompt (or any input) to regenerate.

Outputs: image (IMAGE tensor, batch of n) and mask (MASK tensor). Errors are logged to the ComfyUI console.

ComfyUI's IMAGE type is RGB, so when background = transparent the alpha channel comes out on mask instead — following the LoadImage convention, mask = 1 - alpha, meaning a transparent region reads as selected (1.0). The image preview will look black in those regions; that is the alpha being discarded for display, not a failed generation. To get a transparent file, feed image and mask into Join Image with Alpha (it inverts the mask internally, so no InvertMask in between) and save the result. Opaque output gives an all-zero mask.

🤖 Imagent: OpenAI Image Edit

Image editing, inpainting, and multi-reference compositing via images.edit.

Parameter	Type	Values / Notes
`prompt`	STRING	Description of the desired edit
`model`	DynamicCombo	Same three models; switching swaps the options below.
↳ `size`	COMBO	Same as the generate node.
↳↳ `custom_width` / `custom_height`	INT	Appear only when `size = custom`. Same rules as the generate node.
↳ `background`	COMBO	gpt-image-2.5: `auto`/`opaque`/`transparent`; gpt-image-2: `auto`/`opaque`.
`images`	IMAGE (auto-grow)	Reference image(s) to edit — grows up to 16 slots; at least one required.
`quality`	COMBO	`auto`, `low`, `medium`, `high`, plus `xhigh` / `max` on gpt-image-2.5.
`output_format`	COMBO	`png`, `jpeg`, `webp`
`moderation`	COMBO	`auto` (default), `low`
`n`	INT	1–8 images per call
`mask` (optional)	MASK	White = region to edit. Inpainting requires exactly one reference image.

Rows marked ↳ live inside the dynamic model widget; ↳↳ rows appear only when their parent option is selected.

No input_fidelity widget: every model shipped here always uses high input fidelity, and passing the parameter is an error. It only applied to the retired gpt-image-1.x models.

Outputs: image (IMAGE tensor, batch of n) and mask (MASK tensor). Errors are logged to the ComfyUI console.

Quick-start recipes:

Edit: connect one image to images, write a prompt, leave mask disconnected.
Inpaint: connect one image + mask (white = area to repaint), write a prompt.
Multi-reference: connect several images (the input grows as you wire them up), write a prompt. Mask not supported for multi-image calls.

🛠️ Development

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest -q

Smoke testing with Docker

Set your API key first — either export OPENAI_API_KEY in your shell, or copy config.example.json → config.json and add your key. Then:

docker compose -f docker/docker-compose.yml up -d --build

ComfyUI will be available at http://localhost:8188 with Imagent pre-loaded. For Python changes, restart the container. The repo is bind-mounted into the container's custom_nodes/ directory.

🐾 The story behind the name

Imagent = image + agent. A small model-driven agent that images things into existence — and edits them once they're there.

It comes from Wallrus, whose own name blends a social wall with a walrus. Two friendly ideas, one tool: straightforward, reliable image generation without the middleman.

💙 Sponsored by Wallrus

ComfyUI-Imagent is proudly sponsored by Wallrus. If Imagent makes your ComfyUI workflow nicer, go say hi. 👋

README.md Unescape Escape

ComfyUI-Imagent