OpenAIGPTImageNodeV2 - ComfyUI Built-in Node Documentation

This node generates images using OpenAI’s GPT Image API. It supports five models — gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2, gpt-image-1.5, and gpt-image-1 — lets you attach reference images for image editing, and can use a mask to specify which parts of an image to replace.

Inputs

Common Inputs

These inputs are always visible.

Parameter	Description	Data Type	Required	Range
`model`	The OpenAI GPT Image model to use. Selecting a model reveals additional parameters specific to that model.	DYNAMIC_COMBO	Yes	`"gpt-image-2.5-flare"` `"gpt-image-2.5-sunburst"` `"gpt-image-2"` `"gpt-image-1.5"` `"gpt-image-1"`
`prompt`	Text prompt for GPT Image (default: `""`).	STRING	Yes	N/A
`n`	How many images to generate (default: `1`).	INT	Yes	1 to 8
`seed`	Seed for reproducibility (default: `0`). Not implemented yet in backend.	INT	Yes	0 to 2147483647

gpt-image-2.5-flare and gpt-image-2.5-sunburst Inputs

These inputs appear when model is set to gpt-image-2.5-flare or gpt-image-2.5-sunburst. Both models share the same parameter set.

Parameter	Description	Data Type	Required	Range
`model.size`	Image size. Select “Custom” to use the custom width and height (default: `"auto"`).	COMBO	Yes	`"auto"` `"1024x1024"` `"1024x1536"` `"1536x1024"` `"2048x2048"` `"2048x1152"` `"1152x2048"` `"3840x2160"` `"2160x3840"` `"Custom"`
`model.custom_width`	Used only when `model.size` is “Custom”. Must be a multiple of 16 (default: `1024`).	INT	No	480 to 3840 (step 16)
`model.custom_height`	Used only when `model.size` is “Custom”. Must be a multiple of 16 (default: `1024`).	INT	No	480 to 3840 (step 16)
`model.background`	Return image with or without background (default: `"auto"`).	COMBO	Yes	`"auto"` `"opaque"` `"transparent"`
`model.quality`	Image quality, affects cost and generation time (default: `"low"`).	COMBO	Yes	`"low"` `"medium"` `"high"` `"xhigh"` `"max"`
`model.images`	Optional reference image(s) for image editing. Up to 16 images. See Reference Inputs for details.	IMAGE	No	0 to 16
`model.mask`	Optional mask for inpainting (white areas will be replaced). Requires exactly one reference image.	MASK	No	N/A

gpt-image-2 Inputs

These inputs appear when model is set to gpt-image-2.

Parameter	Description	Data Type	Required	Range
`model.size`	Image size. Select “Custom” to use the custom width and height (default: `"auto"`).	COMBO	Yes	`"auto"` `"1024x1024"` `"1024x1536"` `"1536x1024"` `"2048x2048"` `"2048x1152"` `"1152x2048"` `"3840x2160"` `"2160x3840"` `"Custom"`
`model.custom_width`	Used only when `model.size` is “Custom”. Must be a multiple of 16 (default: `1024`).	INT	No	480 to 3840 (step 16)
`model.custom_height`	Used only when `model.size` is “Custom”. Must be a multiple of 16 (default: `1024`).	INT	No	480 to 3840 (step 16)
`model.background`	Return image with or without background (default: `"auto"`).	COMBO	Yes	`"auto"` `"opaque"`
`model.quality`	Image quality, affects cost and generation time (default: `"low"`).	COMBO	Yes	`"low"` `"medium"` `"high"`
`model.images`	Optional reference image(s) for image editing. Up to 16 images. See Reference Inputs for details.	IMAGE	No	0 to 16
`model.mask`	Optional mask for inpainting (white areas will be replaced). Requires exactly one reference image.	MASK	No	N/A

gpt-image-1.5 and gpt-image-1 Inputs

These inputs appear when model is set to gpt-image-1.5 or gpt-image-1. Both models share the same parameter set.

Parameter	Description	Data Type	Required	Range
`model.size`	Image size (default: `"auto"`).	COMBO	Yes	`"auto"` `"1024x1024"` `"1024x1536"` `"1536x1024"`
`model.background`	Return image with or without background (default: `"auto"`).	COMBO	Yes	`"auto"` `"opaque"` `"transparent"`
`model.quality`	Image quality, affects cost and generation time (default: `"low"`).	COMBO	Yes	`"low"` `"medium"` `"high"`
`model.images`	Optional reference image(s) for image editing. Up to 16 images. See Reference Inputs for details.	IMAGE	No	0 to 16
`model.mask`	Optional mask for inpainting (white areas will be replaced). Requires exactly one reference image.	MASK	No	N/A

Reference Inputs

Parameter	Description	Data Type	Required	Range
`model.images`	Growable slot: connect 1..N items (e.g. `image_1`…`image_16`); up to 16 reference images for all models.	IMAGE	No	1 to 16
`model.mask`	Optional mask for inpainting (white areas will be replaced). Requires exactly one reference image.	MASK	No	N/A

Parameter Constraints and Limitations:

When model.size is “Custom” (gpt-image-2.5-flare, gpt-image-2.5-sunburst, and gpt-image-2 only), model.custom_width and model.custom_height must both be multiples of 16, the longest edge must not exceed 3840, the aspect ratio must not exceed 3:1, and the total pixel count must be between 655,360 and 8,294,400.
model.mask requires exactly one reference image in model.images: it cannot be used without an image, and it cannot be used with more than one image.
When model.mask is used, its height and width must match the height and width of the reference image.
When model.images is provided, the node runs in image editing mode; without model.images, it generates images from the prompt alone.
Reference images and the mask are downscaled before being sent to the API.
"xhigh" and "max" quality levels are only available for gpt-image-2.5-flare and gpt-image-2.5-sunburst.
The "transparent" background option is available for gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-1.5, and gpt-image-1, but not for gpt-image-2.
seed is currently not implemented in the backend.

Outputs

Output Name	Description	Data Type
`image`	The generated image or images. All returned images are stacked into one batch; if their dimensions differ, they are resized to match the first image.	IMAGE

This documentation was AI-generated. If you find any errors or have suggestions for improvement, please feel free to contribute! Edit on GitHub

Source fingerprint (SHA-256): 4f77b79f9f432a1f2e0fd814012aebe7cc42a8aa983ee9a61f3b32984bf65148

​Inputs

​Common Inputs

​gpt-image-2.5-flare and gpt-image-2.5-sunburst Inputs

​gpt-image-2 Inputs

​gpt-image-1.5 and gpt-image-1 Inputs

​Reference Inputs

​Outputs