Generate Image

./scripts/generate_image "A red fox in autumn forest" -o fox.png
./scripts/generate_image "Make the sky purple" -i photo.jpg -o edited.png

Requirements

Routing picks the key automatically; only the one for the chosen model is needed.

• OPENAI_API_KEY — for gpt-image-* (default route, OpenAI Images API via the OpenAI SDK, not OpenRouter)
• OPENROUTER_API_KEY — for google/gemini-* (OpenRouter chat-completions)

Models

gpt-image-2.5-flare is the cheaper/faster OpenAI sibling; same flags.

Routing

Fresh flat-vector icon, crisp edges?        → Gemini + --size 2K -r high
Wordmark / brand-color logo?                → default
Edit preserving existing layout/colors?     → default
  …illustrated character w/ accent colors   → Gemini + -i ref
Exact extended aspect (4:1, 8:1, 1:8)?      → Gemini + -a
>3840px on an edge?                         → Gemini + --size 4K
webp / jpeg output, or quality tier?        → default + --format / -q
True transparent PNG?                       → chroma bg → remove-background

Options

The output file extension does not set the format — --format does (gpt-image only); Gemini always returns PNG bytes regardless of the filename you give -o.

Aspect → size mapping (gpt-image)

-a maps to discrete sizes: portrait ratios (9:16 2:3 3:4 4:5 1:4 1:8) → 1024x1536, landscape (16:9 3:2 4:3 5:4 21:9 4:1 8:1) → 1536x1024, otherwise 1024x1024. For an exact ratio pass --size WxH instead (multiples of 16, 1:3–3:1, ≤3840/edge); anything wider than 3:1 needs Gemini.

Transparent backgrounds — chroma-key workflow

No route returns a real alpha channel (gpt-image rejects background=transparent at the API level; Gemini renders opaque). Generate on a solid chroma color, then segment:

./scripts/generate_image "BrandName app icon on a solid magenta #FF00FF chroma-key background, no magenta anywhere in the icon itself, icon fills the frame" -o icon-chroma.png
../remove-background/scripts/remove_background icon-chroma.png -o icon.png --crop --padding 32
sips -g hasAlpha icon.png   # expect hasAlpha=yes

remove-background uses BiRefNet segmentation, not color keying, so any background works — but a high-contrast non-brand chroma improves edge accuracy around thin strokes and letterform counters. Name the hex in the prompt (models track hex better than color names) and tell the model not to use it elsewhere.

Failure modes

Prompting notes

• Pass hex codes for brand colors; enumerate what to preserve on an edit ("keep the rounded-square tile, the letterform, the corner badge position") and anchor with "exactly the reference but …".
• For character consistency pass the reference via -i on every call and list each accent color; prompt-only consistency drifts.
• Pair with remove-background for alpha.