GPT Atelier

OpenAI GPT Image generation and editing. Wraps both the Image API (one-shot) and Responses API (multi-turn conversational) with 6 scripts covering generate, edit, compose, converse, stream, and test workflows.

Prerequisite: OPENAI_API_KEY environment variable.

Models

Quick Start

# Test connectivity
python3 scripts/test_connection.py --check-models

# Generate an image
python3 scripts/generate_image.py "A Minoan bull-leaper under golden light"

# Compare models side-by-side (HTML page)
python3 scripts/compare_models.py "A bronze seal stamp in Minoan style" --all --open

# Edit with mask
python3 scripts/edit_image.py "Replace the sky with a dramatic sunset" photo.png --mask sky_mask.png

# Compose from references
python3 scripts/compose_images.py "Create a gift basket containing these items" item1.png item2.png item3.png

# Multi-turn editing session
python3 scripts/converse_image.py

# Streaming with partial images
python3 scripts/stream_image.py "An ancient fresco being restored" --partials 3

Image API scripts share: --output DIR, --filename NAME, --quality low|medium|high, --format png|jpeg|webp, --fast, --mini. converse_image.py uses --orchestrator instead of --fast/--mini.

Core Workflows

1. Text-to-Image Generation

python3 scripts/generate_image.py "prompt" [options]

# Product photography
python3 scripts/generate_image.py \
  "High-end product photography of luxury watch on black marble, dramatic key light, f/5.6, commercial quality" \
  --size square --quality high

# Budget thumbnails
python3 scripts/generate_image.py "Quick sketch of a coffee cup" --mini --quality low

# Multiple variations
python3 scripts/generate_image.py "Logo design for a tech startup" --n 4 --size square

2. Image Editing

python3 scripts/edit_image.py "instruction" input.png [options]

Additional options: --mask, --images (extra references).

Auto-converts B&W masks to RGBA (requires Pillow: pip install Pillow).

# Region-aware edit with mask
python3 scripts/edit_image.py "Add a flamingo to the pool" lounge.png --mask pool_mask.png

# Full-image restyle
python3 scripts/edit_image.py "Convert to watercolor painting style" photo.jpg

# Edit with reference images
python3 scripts/edit_image.py "Replace the car with this bicycle" street.png --images bicycle.png

3. Multi-Reference Composition

python3 scripts/compose_images.py "instruction" img1.png img2.png [img3.png ...] [options]

Requires 2+ reference images. The model creates a new image incorporating all references.

python3 scripts/compose_images.py \
  "Create a mood board combining these design elements" \
  texture.png palette.png sketch.png --size landscape

4. Multi-Turn Conversational Editing (Responses API)

python3 scripts/converse_image.py [prompt] [options]

Without a prompt, enters interactive REPL. Maintains conversation state via previous_response_id.

# Interactive session
python3 scripts/converse_image.py --auto-save
> A cyberpunk street scene at night
> Now add neon signs with Japanese text
> Make it rain and add reflections
> /save final_scene

# Single-shot
python3 scripts/converse_image.py "Design a coffee brand logo" --output ./logos

Interactive commands: /save, /action auto|generate|edit, /model, /clear, /history, /help, /quit.

Attach images with @path: @logo.png Add this logo to the top-right corner.

Additional options:

5. Model Comparison (HTML Page)

python3 scripts/compare_models.py "A Minoan bull-leaper" --open
python3 scripts/compare_models.py "prompt" --all --open
python3 scripts/compare_models.py "" --list-models

Generates the same prompt across multiple models and outputs a dark-themed HTML comparison page. See references/compare-models-reference.md for full options.

6. Streaming with Partial Images

python3 scripts/stream_image.py "prompt" --partials N [options]

Outputs partial images as they generate, then the final image.

# Stream with 3 progressively sharper partials
python3 scripts/stream_image.py "A detailed architectural drawing" --partials 3 --save-partials

Additional option: --save-partials to save intermediate images.

Prompting Quick-Hits

1. Lead with scene/style, not subject. First words carry highest visual weight. Specify intended use (ad, UI mockup, editorial) so the model picks the right polish level.
2. Always double-quote literal text. "HELLO WORLD" engages the high-accuracy text rendering engine.
3. Pixel dimensions in prompt. For custom aspect ratios, append "Output in exactly WxH (R:R ratio) resolution" — the API size param alone is unreliable. Done automatically by inject_size_hint() for gpt-image-2.
4. Use --thinking for complex scenes. The orchestrator model matters — Thinking models produce significantly better multi-element compositions.
5. Generate fresh, don't edit. Reference-image editing on gpt-image-2 produces yellow tint and poor prompt adherence. For design-final work, generate from scratch.

See references/prompting-guide.md for full details.

When to Use GPT Atelier vs Nano Banana Pro

Cost Control

Start with --quality low ($0.006/image) for ideation. Graduate to medium ($0.05) for review, high ($0.21) for final assets. Use --fast for cheaper generation, --mini for maximum cost savings. Use --format jpeg for faster response times.

Script Reference

Reference Documentation