---
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.
