gpt-image-2

name	gpt-image-2
description	Use when building or editing a Nebula graph containing a gpt-image-2-* node (generate, edit, fal-generate, fal-edit) or when the user asks to use gpt-image-2 inside Nebula. Covers Nebula-specific node IDs, param names, and UI wiring.

GPT Image 2 — Nebula Integration

OpenAI's gpt-image-2 (released 2026-04-21, snapshot gpt-image-2-2026-04-21) is available in Nebula via four nodes.

Node matrix

Node ID	Path	BYOK key	When to pick
gpt-image-2-generate	OpenAI direct	OPENAI_API_KEY	Text→image, full streaming previews, need partial frames in canvas
gpt-image-2-edit	OpenAI direct	OPENAI_API_KEY	Image edit / inpainting with up to 10 reference images + optional mask
gpt-image-2-fal-generate	FAL proxy	FAL_KEY	Text→image, no OpenAI org-verification needed, pay-per-image
gpt-image-2-fal-edit	FAL proxy	FAL_KEY	Edit via FAL

All four use executionPattern: "stream". Partial previews render in the canvas as they arrive.

OpenAI-direct params (generate + edit)

Param	Values	Default	Notes
size	auto, 1024x1024, 1536x1024, 1024x1536, 2048x2048, 2048x1152, 3840x2160, 2160x3840	auto	4K sizes cost significantly more
quality	auto, low, medium, high	auto	~$0.006 / $0.053 / $0.211 at 1024²
output_format	png, jpeg, webp	png
output_compression	0–100	90	Only applied when format != png
moderation	auto, low	auto	low is less restrictive

Edit node also accepts: images (Image, multiple, up to 10), mask (alpha-channel PNG, same size + format as first image).

FAL-routed params

FAL uses slightly different naming: image_size (not size), num_images (not n). Same sizes and quality values, but num_images maxes at 4 (FAL cap). Otherwise identical semantic surface.

What's NOT supported (and Nebula does not expose)

• background: transparent — v1 supported it, v2 does not. If a user asks for transparent backgrounds, suggest chaining a remove-background node downstream instead.
• input_fidelity — gpt-image-2 always processes inputs at high fidelity; the param must be omitted.
• n > 1 — OpenAI rejects n > 1 when stream=true, and our nodes always stream. The n/Count param is not exposed on the OpenAI-direct nodes. Run the node multiple times for multiple images. (FAL nodes expose num_images because FAL may handle this differently — verify during UAT.)
• partial_images (Preview Frames) — removed from the OpenAI-direct node defs. Small/fast generations rarely emit partials (OpenAI docs: "you may not receive the full number of partial images you requested"), and we defaulted to none anyway. FAL nodes still expose it for now pending UAT.

Cost guidance

• Draft iteration → quality: low at 1024x1024 ≈ $0.006 each.
• Hero asset → quality: high at chosen aspect ratio.
• 4K → token cost scales roughly with pixel count; use sparingly.
• Batch API (50% off) is not wired up in Nebula yet — handle in a later phase.

When editing a prompt for this node

If the user asks Codex to write or refine a prompt that will feed into gpt-image-2-*, consult docs/model-providers/openai/gpt-image-2.md for provider notes and prompting constraints before creating the graph.

Known surprises

• OpenAI direct requires Organization Verification — if the user gets "org isn't verified" errors, direct them to https://platform.openai.com/settings/organization/general.
• FAL path uses different param names: image_size not size, num_images not n.
• Mask is prompt-guided — the prompt must describe the full desired image, not just the masked region.
• Up to 10 reference images in the edit endpoint; the mask applies to the first image when supplied.
• Streaming: enable partial_images (default 2) to see preview frames in the canvas as the image renders. Set to 0 for final-only.
• SSE event namespaces differ by endpoint: /v1/images/generations emits image_generation.completed / image_generation.partial_image, but /v1/images/edits emits image_edit.completed / image_edit.partial_image. Our parser accepts both. OpenAI's docs don't highlight this distinction — discovered during UAT 2026-04-22.