# Finisher — GPT Image 2 (the only one)

> **PORTABILITY NOTE.** Published from Imperium's internal operating system. Paths starting
> with `~/.claude/`, `/Users/alex/...`, `<repo-root>/`, or `scripts/`, plus Drive/Telegram
> distribution steps and CLI wrappers, are the author's machine conveniences — substitute your
> own tooling. The prompts, model choices, parameters, and QA gates are the portable substance.

GPT Image 2 is the ONLY premium finisher. Call it **directly via the OpenAI API** (`OPENAI_API_KEY`), never
through Higgsfield or any other service. Higgsfield is a separate provider; its models reinterpret the UI and
garble text (tested and rejected 2026-07-03). Do not use them to finish a still. GPT Image 2's `edit` endpoint
processes the input image at **locked high fidelity automatically** — that's what preserves the layout, fonts,
and every string while it adds the finish.

## Run it
```bash
node scripts/gpt-finish.mjs --image code-render.png --out hero.png --preset premium-3d --n 3
```
Presets: `premium-3d`, `reflection`, `desk-scene`, `gradient-bg`, `glass`, `studio`. Or `--prompt "..."` for a
custom finish. The script auto-appends a guard clause ("keep every element and all text exactly, only add the
finish"). It always uses the `edit` endpoint (anchored to your render) — never pure text-to-image, which
invents everything.

## API facts
- Endpoint: `POST /v1/images/edits` (multipart: `image` + `prompt`). Use this for product UI.
- Model ids on the key: `gpt-image-2` (default), `gpt-image-2-2026-04-21`, `gpt-image-1.5`, `gpt-image-1`,
  `chatgpt-image-latest`.
- Sizes: `1024x1024`, `1536x1024` (landscape hero), `1024x1536` (portrait — match the source aspect), `auto`.
- Quality: use `medium` — `high` frequently drops the long connection. Each call ~50–60s. Reference images
  bill at the high-fidelity input rate regardless of output quality.
- Returns `b64_json`. Non-deterministic → generate `--n 3+` and curate. Small drifts happen (e.g. a word may
  get re-capitalized) — that's why the deterministic **code render stays the source of truth** for anything
  that must be consistent; the finish is a curated hero pass.
- Auth: `OPENAI_API_KEY` from env / `--env-file` / `./.env`. In Alex's setup the REAL key is in
  `/Users/alex/Documents/Alex OS/.env` (set `ENV_FILE` to that path). `~/.env` contains a
  placeholder ("your_ope…here") — do not use it (verified 2026-07-04).
- **Long custom prompts can hang the edit endpoint.** Repeated `socket hang up` on every retry while other
  calls succeed = prompt too long, not upload size. Keep `--prompt` to preset length (~2-3 sentences) or use
  a `--preset`; observed 2026-07-04 (a ~90-word prompt failed 12/12 attempts, the preset succeeded at once).

## Tweak vocabulary (how to spec the look)
Every visual knob below maps to a phrase you add to `--prompt`. Keep the guard clause intact ("keep the layout
and all text exactly, only add …"). Combine freely; be specific with values.

| Knob | Say it like | Notes |
|---|---|---|
| **Background palette** | "soft gradient background, deep green → warm bone, very gentle" | Name exact colors/hex if you have a brand palette; say "matte, no banding". For Imperium (greens only, BRAND-BOOK §3): Racing Green `#11462C`, Mint `#4CB782`, Bali `#3FA085`, Deep `#0A1F14`, neutrals Paper `#F7F6F1` / Sage `#EDF2E8` / Bone `#F4F1EA` (no pure white, no warm browns, no bright accents). |
| **Blur / depth of field** | "shallow depth of field, far edge softly out of focus" / "keep the whole panel sharp, blur only the background" | Specify what stays sharp so text isn't softened. |
| **Framing / crop** | "centered with generous margin" / "tight crop, panel bleeds off the top-right" / "portrait 4:5" | Also set `--size` to the aspect you want. |
| **Drop shadow** | "soft floating contact shadow below the panel, long and diffuse" / "tight crisp shadow" | Control softness + direction + distance. |
| **Reflection** | "subtle mirror reflection beneath, fading out" / "faint glass surface reflection on the screen" | |
| **Material** | "frosted glassmorphism panel with a faint edge highlight" / "matte card" / "glossy screen" | |
| **Environment** | "on a marble desk with a hint of a plant, window light" / "floating in a clean studio" / "on a dark moody backdrop with rim light" | The desk/scene presets are starting points. |
| **Lighting** | "soft studio softbox from upper-left" / "warm golden-hour rim light" / "cool even light" | |
| **Grain / mood** | "subtle film grain, premium and expensive" / "clean and minimal, no grain" | |

Example combined tweak:
```bash
node scripts/gpt-finish.mjs --image render.png --out hero.png --size 1024x1536 \
  --prompt "Frosted glassmorphism panel with a faint edge highlight, floating on a soft gradient background \
  (deep British racing green #11462C into deep forest green #0A1F14, matte, no banding), long diffuse contact shadow, \
  soft studio light from upper-left, subtle grain."
```

## Motion / video (out of scope for the still finisher)
If a hero needs to move, keep it **code-native** so text stays crisp and consistent: animate the live HTML/CSS
mockup with GSAP, or render a camera move / staged reveal with Remotion (see the `remotion-best-practices`
skill if present). Do not use an image/video model to "animate" a text UI — it will drift the content, the
same reason Higgsfield is out for stills.
