# OpenAI gpt-image-1.5 — operational reference

Read this file before writing any prompt for `gpt-image-1.5`. Sources: OpenAI Cookbook gpt-image-1.5 prompting guide (primary), OpenAI API docs, fal.ai prompt guide.

## API surface

- **Endpoint (generate):** `POST https://api.openai.com/v1/images/generations`
- **Endpoint (edit/inpaint):** `POST https://api.openai.com/v1/images/edits`
- **Model ID:** `gpt-image-1.5`
- **Auth:** `Authorization: Bearer $OPENAI_IMAGE_API_KEY`

The bundled `scripts/openai-image.sh` wraps both endpoints. Read [../scripts/README.md](../scripts/README.md) for invocation.

## Parameter cheatsheet

| Param | Values | When to use |
|---|---|---|
| `quality` | `low` \| `medium` \| `high` \| `auto` | `low` for ideation grids; `high` for finals and **anything with text**. Cookbook: use `high` for "dense layouts or heavy in-image text." |
| `size` | `1024x1024` \| `1024x1536` \| `1536x1024` \| `auto` | Square for logos/icons; portrait for mobile UI; landscape for hero/dashboard. **No other sizes are supported** — no 512, no 2048. |
| `background` | `opaque` \| `transparent` \| `auto` | `transparent` for logos/icons/cutouts. Requires `output_format=png` or `webp`. Works best at `medium`+. |
| `output_format` | `png` \| `jpeg` \| `webp` | `png` for logos, icons, anything with text or transparency. `jpeg` for product photos / hero photos. `webp` for web with transparency. |
| `output_compression` | `0-100` (jpeg/webp only) | Default usually fine. |
| `n` | integer | Cookbook: `n=4` for ideation. Single call returns multiple coherent variants — better than 4 sequential calls. |
| `moderation` | `auto` \| `low` | `low` for edgy marketing / political / historical work. Stays within policy. |
| `response_format` | `b64_json` \| `url` | `b64_json` for server pipelines (the bundled script uses this). `url` for browser delivery. |
| `stream` + `partial_images` | bool + 0-3 | Streams up to 3 intermediates. Each partial = +100 output tokens. Skip for batch work. |
| `input_fidelity` *(edit only)* | `low` (default) \| `high` | **gpt-image-1.5 specific: `high` preserves the FIRST 5 input images at higher fidelity** (vs only the first one on gpt-image-1). This is the single biggest reason to use 1.5 for brand work. |
| `action` *(Responses API only)* | `auto` \| `generate` \| `edit` | Force generate-new vs edit-in-place when ambiguous. |

## Prompt structure — house rules

The cookbook canonical structure:

```
[background/scene] → [subject] → [key details] → [constraints]
```

**Use labeled segments or line breaks, not single paragraphs.** Cookbook quote: *"For complex requests use short labeled segments or line breaks instead of one long paragraph."*

**Length:** 2-5 sentences for simple work, 8-15 for UI mockups / detailed scenes. Vagueness is penalized; length is not.

**No prompt-syntax tricks.** No weighted tokens, no `::` operators. Pure natural language.

**Negative prompts work.** Unlike Gemini, GPT respects declarative exclusions inside the main prompt:
- `"No watermark"`
- `"No extra text"`
- `"No logos or trademarks"`
- `"Do not add new elements"`
- `"Do not change the background, camera angle, framing, or image quality"`

**Iteration discipline:** Cookbook: *"Start with a clean base prompt, then refine with small, single-change follow-ups."* When iterating, **repeat the preserve-list every turn** — drift compounds.

**Intended-use cue.** Always state the deliverable type: "ad," "UI mock," "infographic," "logo sheet." This sets the model's polish level.

## Vocabulary that works

**Photography terms** outperform generic quality words ("8K," "ultra-detailed," "masterpiece"):

- **Lens:** "35mm lens," "50mm lens," "35mm film photograph," "macro"
- **Aperture:** "shallow depth of field," "deep focus"
- **Lighting:** "soft coastal daylight," "golden hour," "rim lighting from behind," "diffused overcast light," "soft box lighting eliminating harsh shadows," "pools of amber light," "tasteful bokeh lights"
- **Film:** "subtle film grain," "natural color balance"

**Composition:** "centered," "eye-level," "medium close-up," "wide-angle view," "close-up macro shot," "bird's eye view," "top-down," "Dutch angle," "generous padding"

**Materials/texture:** "weathered skin," "visible wrinkles, pores," "worn materials," "fabric wear," "stitching repairs," "faded," "realistic textures"

**Style references:** "flat design," "vector-like shapes," "hand-painted watercolor look," "Escher-inspired architecture," "documentary photography style," "professional studio photography," "cinematic composition," "whimsical and friendly," "technical illustration"

**Realism anchors:** "honest and unposed," "no glamorization," "no heavy retouching," "grounded, authentic, and unstyled, as if captured in a real moment"

## Vocabulary that fails

- **Contradictions:** "photorealistic cartoon," "minimalist detailed." Resolve by describing the blend: "photorealistic rendering with subtle anime-inspired character proportions."
- **Generic quality inflation:** "8K," "ultra-detailed," "masterpiece," "best quality" — camera/composition terms steer realism more reliably.
- **Concept-art language for UI work:** "design sketch," "wireframe concept," "mood exploration" produce sketch-like output. **Describe UI as if it already exists.**
- **Overusing "cinematic"** for documentary-style work — explicitly add `Avoid cinematic lighting, dramatic color grading, or stylized composition` for grounded realism.
- **Vague subjects without environment:** "A red sports car" is weak. Add setting, lighting, time-of-day.

## Text rendering rules

Cookbook core rule: **put literal text in quotes or ALL CAPS, and specify typography details (font style, size, color, placement) as constraints.**

Verbatim cookbook example:
```
Billboard text (EXACT, verbatim, no extra characters): "Fresh and clean"
Typography: bold sans-serif, high contrast, centered, clean kerning.
```

Techniques that improve legibility:

1. **Wrap literal text in double quotes.** The model treats quoted content as verbatim.
2. **Always use `quality="high"`** for any image with text.
3. **Spell tricky words letter-by-letter** for brand names: `"F-I-E-L-D & F-L-O-U-R"`.
4. **Demand uniqueness** to prevent hallucinated bonus labels: `"Include ONLY this packaging text (verbatim): [exact copy]"`.
5. **Specify typography:** "bold sans-serif," "thin serif," "clean kerning," "centered alignment."
6. **Specify contrast:** "high contrast," "dark text on light background."

**Limits:** dense paragraphs and very small UI labels still struggle. Strings over ~30-40 chars start to degrade. For critical brand names always render at `high` quality.

## Reference images / edit endpoint

**The 5-reference superpower.** On `gpt-image-1.5`, `input_fidelity="high"` preserves the **first 5 input images** at higher fidelity. You can pass logo + color swatch + typography specimen + product reference + moodboard, and all five inform the output without being mangled.

**Indexing convention:** *"Reference each input by index and description"*: `"Image 1: product photo. Image 2: style reference. Image 3: brand color palette."` Then describe interactions: `"apply Image 2's style to Image 1."`

### Cookbook verbatim edit examples

**Virtual try-on (identity preservation):**
```
Edit the image to dress the woman using the provided clothing images. Do
not change her face, facial features, skin tone, body shape, pose, or
identity in any way. Preserve her exact likeness, expression, hairstyle,
and proportions. Replace only the clothing, fitting the garments naturally
to her existing pose and body geometry with realistic fabric behavior.
Match lighting, shadows, and color temperature to the original photo so
the outfit integrates photorealistically, without looking pasted on. Do
not change the background, camera angle, framing, or image quality, and
do not add accessories, text, logos, or watermarks.
```

**Sketch-to-render:**
```
Turn this drawing into a photorealistic image. Preserve the exact layout,
proportions, and perspective. Choose realistic materials and lighting
consistent with the sketch intent. Do not add new elements or text.
```

**Background removal (transparent PNG cutout):**
```
Extract the product from the input image. Output: transparent background
(RGBA PNG), crisp silhouette, no halos/fringing. Preserve product geometry
and label legibility exactly. Optional: subtle, realistic contact shadow
in the alpha (no hard cut line). Do not restyle the product; only remove
background and lightly polish.
```

**Style transfer:**
```
Use the same style from the input image and generate a man riding a
motorcycle on a white background.
```

**Multi-image compositing:**
```
Place the dog from the second image into the setting of image 1, right
next to the woman, use the same style of lighting, composition and
background. Do not change anything else.
```

### Brand-consistent variant workflow (5-reference recipe)

1. Pass: logo PNG, primary color swatch, secondary color swatch, typography specimen, vibe reference (5 inputs).
2. `input_fidelity="high"`, `quality="high"`.
3. Prompt:
```
Image 1 is the primary logo.
Image 2 is the brand primary color.
Image 3 is the brand secondary.
Image 4 is the brand typography.
Image 5 is the vibe reference.

Generate a [DELIVERABLE] that:
- uses the exact logo from Image 1 without distortion
- strictly adheres to the palette of Images 2-3
- uses typography matching Image 4's weight and proportions
- captures the mood of Image 5

Do not modify the logo shape, do not introduce new colors, do not
substitute fonts.
```

### Mask-based inpainting

Pass an alpha-channel mask (transparent = edit region, opaque = preserve). Mask must match input dimensions, be <50MB, contain an alpha channel.

```python
from PIL import Image
mask = Image.open(path).convert("L")
mask_rgba = mask.convert("RGBA")
mask_rgba.putalpha(mask)
```

On 1.5, masks preserve unmasked areas (faces, backgrounds, logos) much better than 1.

## Failure modes

- **Text fidelity degrades on dense small-font layouts.** Iterate with small wording/layout tweaks; never expect perfect first pass on paragraph-heavy designs.
- **Multi-iteration drift** — fix by repeating the preserve list every turn.
- **Overloaded prompts produce chaos** — break into base + iteration.
- **Concept-art language for UI** produces sketchy-looking UI. Use shipped-product language ("a real, well-designed, beautiful app").
- **Latency:** complex prompts may require up to 2 minutes.
- **Resolution ceiling:** max 1536 on the long side. For 4K deliverables, generate at 1536 and upscale externally (Topaz, Real-ESRGAN).
- **Hidden reasoning tokens add cost** — budget ~10-20% buffer over visible cost.
- **Moderation refuses:** explicit content, graphic violence, real-person impersonation, disallowed/trademarked logos.

## Pricing (per image, OpenAI API as of April 2026)

| Quality | 1024×1024 | 1024×1536 (portrait) | 1536×1024 (landscape) |
|---|---|---|---|
| `low` | $0.009 | $0.013 | $0.013 |
| `medium` | $0.034 | $0.050 | $0.050 |
| `high` | $0.133 | $0.200 | $0.200 |

Each streamed `partial_image` adds +100 output tokens (~$0.003).

Practical numbers:
- Logo exploration `n=4` low square: ~$0.04/call total
- Final logo high square: $0.13
- Hero shot high landscape: $0.20
- UI mockup high portrait: $0.20

## Canonical examples by asset type (verbatim from cookbook)

**Logo (Field & Flour bakery):**
```
Create an original, non-infringing logo for a company called Field & Flour,
a local bakery. The logo should feel warm, simple, and timeless. Use clean,
vector-like shapes, a strong silhouette, and balanced negative space. Favor
simplicity over detail so it reads clearly at small and large sizes. Flat
design, minimal strokes, no gradients unless essential. Plain background.
Deliver a single centered logo with generous padding. No watermark.
```

**Mobile UI (farmers market):**
```
Create a realistic mobile app UI mockup for a local farmers market. Show
today's market with a simple header, a short list of vendors with small
photos and categories, a small "Today's specials" section, and basic
information for location and hours. Design it to be practical, and easy
to use. White background, subtle natural accent colors, clear typography,
and minimal decoration. It should look like a real, well-designed,
beautiful app for a small local market. Place the UI mockup in an iPhone
frame.
```

**Product hero shot:**
```
High-end product shot on a marble countertop, soft directional studio
lighting, subtle reflections, shallow depth of field, minimal background
with warm beige tones, professional e-commerce look.
```

**Icon set (8-icon grid):**
```
Create a horizontal sequence of 8 tiles, evenly spaced. Each tile must
contain: Top: a bold black number (01-08). Bottom: the corresponding item.

Items: light bulb, hourglass, compass, magnifying glass, calendar,
alarm clock, map pin, flag.

Style: flat illustration, single-weight 2px outlines, no fill, rounded
corners, centered in each tile at consistent scale. No overlap, no extra
elements, no text labels. Monochrome black on plain white background.
```

**Billboard text (verbatim):**
```
Billboard text (EXACT, verbatim, no extra characters): "Fresh and clean"
Typography: bold sans-serif, high contrast, centered, clean kerning.
```

For more examples (filled in for design tasks), see [../examples.md](../examples.md).