Hypereal AI Image Generator

Generate professional 4K AI images from plain-English concepts. You write ideas in concepts.txt. Gemini Flash turns them into optimized Nano Banana 2 prompts. Hypereal generates and downloads the images.

Working Directory

Run Claude Code from the folder containing generate_prompts.py, generate_images.py, and .env.

Requirements

Python 3.10+ with these packages:

pip install google-genai aiohttp python-dotenv

Execute -- Image Generation Workflow

Step 1: Check Setup

Read .env in the current directory. Verify both keys are set (not empty):

• HYPEREAL_API_KEY -- for image generation
• GEMINI_API_KEY -- for prompt writing (~$0.002/prompt, get key at aistudio.google.com)

If either key is missing, stop and tell the user which one is missing and where to get it:

• Hypereal key: https://hypereal.tech?ref=2mWwuWId
• Gemini key: https://aistudio.google.com (~$0.002 per prompt, pay-per-use, no subscription)

Step 2: Check concepts.txt

Read concepts.txt. Count non-blank, non-comment lines (not starting with #).

If no concepts found:

"Add your image ideas to concepts.txt -- one idea per line. Then run /hypereal-images again."

If concepts found, show a summary of what will be generated.

Step 3: Ask Generation Settings

Ask the user (can answer in one message):

1. Aspect ratio -- 3:2 (landscape), 4:5 (portrait), 1:1 (square), or 9:16 (vertical/wallpaper)?
2. Style -- auto (Gemini decides), photorealistic, or illustrative?
3. Resolution -- 4K (8 credits/image), 2K (4 credits), or 1K (2 credits)?

Defaults: 3:2, auto, 4K.

Step 4: Generate Prompts

Run:

python generate_prompts.py --aspect-ratio [ratio] --style [style]

This reads concepts.txt, calls Gemini Flash for each concept, and saves prompts to prompts.json.

After completion, read prompts.json and show a summary of concept names and prompt IDs.

Step 5: Generate Images

Run:

python generate_images.py --resolution [resolution]

This reads prompts.json, calls the Hypereal API (4 concurrent by default), and downloads images to output/.

Step 6: Report Results

• State how many succeeded and how many failed
• List the filenames of successful images
• If any failed, explain the error and suggest a fix

CLI Quick Reference

python generate_prompts.py                               # generate prompts for all concepts
python generate_prompts.py --aspect-ratio 9:16           # vertical/wallpaper format
python generate_prompts.py --style photorealistic        # force photorealistic track
python generate_prompts.py --dry-run                     # preview prompts without saving
python generate_prompts.py --force                       # regenerate all (overwrite existing)

python generate_images.py                                # generate all prompts in prompts.json
python generate_images.py --dry-run                      # preview without calling API
python generate_images.py --resolution 2K                # fewer credits (4/image vs 8)
python generate_images.py --batch-size 2                 # slower, fewer concurrent requests
python generate_images.py --format png                   # save as PNG instead of JPEG

Error Handling